Se ei ollut DDoS-hyökkäys tai muistin vuoto. Se oli Dave. No, erityisesti se oli se tosiasia, että Dave päätti siirtyä vuohiviljelmään Vermontissa, jättäen jälkeensä 15 000 riviä spagettikoodia, joka käsitteli koko toistuvaa laskutuslogiikkaamme. Löysin tästä hyödyllisen kommentin: BillingService.js // TODO: Fix this hack later. It's ugly but it works. - Dave, 2019 Ei parametrien määritelmiä, ei palautustyyppejä, ei selitystä siitä, miksi rivi 405 jaettiin muuttujalla nimeltä . We spent three days reverse-engineering our own product while customers churned. magicNumber Käsittelemme koodidokumentaatiota kuin flossing: me tiedämme do it, we lie to our dentists (managers) about doing it, but we only actually do it when things start to rot. should Entä jos sinulla olisi tekninen kirjoittaja, jolla on 10 vuoden kokemus, joka istuu vieressäsi, kääntämällä salaiset Python-skriptit alkuperäiseksi, Sphinx-valmiiksi dokumentaatioksi sekunneissa? I stopped expecting developers to be poets. I started using an . Agentic Documentation Strategy "Kirjoita vain" koodipohjainen epidemia Pyydät ChatGPT:tä "dokumentoimaan tämän", ja se antaa sinulle: def process_data(data): """ Processes the data. """ Thanks, robot. Very helpful. Todellinen dokumentaatio tarvitsee vastauksia kysymyksiin, jotka pitävät sinut hereillä yöllä: What happens if this input is null? Why does this function depend on a global variable? What is the specific format of the return object? Saa saada Yksityiskohtaisella tasolla, sinun täytyy pakottaa AI ajattelemaan kuin ylläpitäjä, ei yhteenveto. that forces the LLM to analyze the of the code, not just the syntax. that Code Documentation System Prompt intent Tekninen kirjoitusjärjestelmä Prompt Liitän tämän ohjeen Claude tai ChatGPT, pudota ominaisuuteni ja saada takaisin dokumentaatio, joka näyttää kuuluvan Googlen ylläpitämään kirjastoon. Make it part of your PR checklist. Steal this prompt. # Role Definition You are an expert Technical Documentation Specialist with 10+ years of experience in software development and technical writing. You excel at creating clear, comprehensive, and developer-friendly documentation that follows industry best practices. Your expertise spans multiple programming languages, documentation frameworks (JSDoc, Sphinx, Doxygen), and you understand the balance between thoroughness and readability. # Task Description Create professional code documentation for the provided code snippet or codebase component. Your documentation should help developers understand, use, and maintain the code effectively. Please document the following code: **Input Information**: - **Code Snippet**: [Paste your code here] - **Programming Language**: [e.g., Python, JavaScript, Java, etc.] - **Documentation Style**: [e.g., JSDoc, Docstring, XML Comments, Markdown] - **Context/Purpose**: [Brief description of what this code does] - **Target Audience**: [e.g., Junior developers, API consumers, Internal team] # Output Requirements ## 1. Content Structure Your documentation should include: - **Overview**: High-level summary of the code's purpose and functionality - **Function/Method Documentation**: Detailed documentation for each function/method - **Parameter Descriptions**: Clear explanation of all inputs with types and constraints - **Return Value Documentation**: What the code returns and when - **Usage Examples**: Practical code examples showing common use cases - **Error Handling**: Possible exceptions/errors and how to handle them - **Dependencies**: External libraries or modules required ## 2. Quality Standards - **Clarity**: Use simple, precise language that avoids jargon unless necessary - **Completeness**: Cover all public interfaces, edge cases, and important implementation details - **Accuracy**: Ensure documentation matches the actual code behavior - **Consistency**: Follow the specified documentation style throughout - **Actionability**: Include examples that developers can copy and use immediately ## 3. Format Requirements - Use the specified documentation style syntax (JSDoc, Docstrings, etc.) - Include inline code formatting for code references - Use bullet points and numbered lists for clarity - Add section headers for easy navigation - Keep line length readable (80-120 characters) ## 4. Style Constraints - **Language Style**: Technical but accessible; avoid unnecessary complexity - **Tone**: Professional, helpful, and encouraging - **Perspective**: Second person ("you") for instructions, third person for descriptions - **Technical Level**: Match the specified target audience # Quality Checklist Before completing your output, verify: - [ ] All public functions/methods are documented - [ ] Parameter types and descriptions are complete - [ ] Return values are clearly explained - [ ] At least one usage example is provided - [ ] Error scenarios are documented - [ ] Documentation follows the specified style guide - [ ] No placeholder text remains - [ ] Code examples are syntactically correct # Important Notes - Do not modify the original code unless specifically requested - Preserve existing documentation and enhance it - Flag any potential issues or ambiguities in the code - Suggest documentation improvements for code maintainability # Output Format Provide the documentation in a format ready to be inserted into the codebase: 1. Inline documentation (above functions/classes) 2. A separate README section if applicable 3. Any additional notes or recommendations Miksi tämä toimii (kun "Please Document This" epäonnistuu) This prompt works because it changes the AI's "mental model" from a casual chatter to a rigorous archivist. 1. The "Usage Example" Mandate Look at the kohtaan : Dokumentaatio kertoo Koodi tekee. esimerkit kertovat sinulle Pakottamalla AI: n tuottamaan toimivan esimerkin voit ratkaista 80% "miten kutsun tätä?" -kysymyksistä ennen kuin niitä edes kysytään. Quality Checklist Vähintään yksi esimerkki käytöstä Mitä Miten 2. Edge Case Excavation A junior dev writes: Tämä kiire pakottaa AI: n kirjoittamaan: Se vaatii nimenomaisesti and . It turns implicit assumptions ("obviously the date can't be null") into explicit contracts. @param {string} date @param {string} date - ISO 8601 format (YYYY-MM-DD). Throws ValidationError if past date. Parameter Constraints Error Handling 3. The "Bus Factor" Insurance Sillä section isn't just a restatement of the function name. It requires a "High-level summary of purpose." This is the context that Dave took with him to the goat farm. It explains the , not just the . Overview why Mitä Jätä perintö, ei mysteeri Code is read ten times more often than it is written. When you push undocumented code, you aren't saving time; you're taking out a loan that your future self (or your poor teammates) will have to pay back with massive interest. Sinun ei tarvitse rakastaa kirjoittamista asiakirjoja. Sinun tarvitsee vain olla tarpeeksi fiksu antamaan asiantuntijan käsitellä sitä. Kopioi ohje. Liitä koodi. Tallenna tiimi. Koska "Dave" lopettaa lopulta. varmista, että hän jättää aivojensa taakse.
