Non è stato un hacker che ha abbattuto la nostra gateway di pagamento lo scorso anno. Era il Dave. Beh, in particolare, è stato il fatto che Dave ha deciso di trasferirsi in una fattoria di capre a Vermont, lasciando dietro di sé 15.000 righe di codice di spaghetti che ha gestito tutta la nostra logica di fatturazione ricorrente. Ho trovato questo commento utile: BillingService.js // TODO: Fix this hack later. It's ugly but it works. - Dave, 2019 Nessuna definizione dei parametri. nessun tipo di ritorno. nessuna spiegazione del perché la riga 405 era divisa da una variabile chiamata Abbiamo trascorso tre giorni ingegnerizzando il nostro prodotto, mentre i clienti si sono schiacciati. magicNumber Trattiamo la documentazione del codice come il flossing: sappiamo che Se lo facciamo, mentiamo ai nostri dentisti (manageri) di farlo, ma lo facciamo solo quando le cose iniziano a rovinarsi. Dovrebbe E se potessi avere uno scrittore tecnico con 10 anni di esperienza seduto accanto a te, trasformando i tuoi script Python criptici in una documentazione pronta per la Sfinx in pochi secondi? Ho smesso di aspettarmi che gli sviluppatori fossero poeti. ho iniziato a usare un . Agentic Documentation Strategy L’epidemia di codebase “solo scritta” La maggior parte della documentazione generata da AI è fluff. Chiedi a ChatGPT di "documentare questo", e ti dà: def process_data(data): """ Processes the data. """ Grazie Robot, molto utile La vera documentazione ha bisogno di rispondere alle domande che ti tengono sveglio di notte: Cosa succede se questa voce è null? Perché questa funzione dipende da una variabile globale? Qual è il formato specifico dell'oggetto di ritorno? per ottenere livello di dettaglio, è necessario costringere l'IA a pensare come un mantenitore, non un sintetizzatore. che costringe il LLM ad analizzare il Il codice, non solo la sintesi. Questo Code Documentation System Prompt Intenzione Il sistema di scrittura tecnica prompt Non scrivo più docstrings. inserisco questo prompt in Claude o ChatGPT, scarico la mia funzione e ricevi la documentazione che sembra appartenere a una libreria mantenuta da Google. Fai parte della tua lista di controllo PR. 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 Perché questo funziona (quando "Please Document This" fallisce) Questo prompt funziona perché cambia il "modello mentale" dell'IA da un chatter casuale a un archivista rigoroso. Il mandato “esempio d’uso” Guardate il Il punto: La documentazione ti dice Il codice fa. Esempi ti dicono Forzando l'IA a generare un esempio di lavoro, si risolve l'80% delle domande "come chiamo questo?" prima che vengano persino chieste. Quality Checklist Almeno un esempio di utilizzo è fornito Che cosa come Scavatura di case edge A Junior Dev ha scritto: Questo prompt costringe l’AI a scrivere: Chiede esplicitamente di e Trasforma i presupposti impliciti ("ovviamente la data non può essere nulla") in contratti espliciti. @param {string} date @param {string} date - ISO 8601 format (YYYY-MM-DD). Throws ValidationError if past date. Parameter Constraints Error Handling L’assicurazione “Bus Factor” Il La sezione non è solo una ridefinizione del nome della funzione. Esso richiede un "Rispetto di alto livello dello scopo." Questo è il contesto che Dave ha portato con sé alla fattoria di capra. Non solo il . Overview Perché Che cosa Lascia un’eredità, non un mistero Quando si spinge il codice non documentato, non si sta risparmiando tempo; si sta prendendo un prestito che il vostro futuro sé (o i vostri poveri compagni di squadra) dovranno pagare con un interesse enorme. Non devi amare la scrittura di documenti, devi solo essere abbastanza intelligente da permettere a uno specialista di gestirli. Copia il prompt. Inserire il codice. Salva il team. Perché "Dave" sta per smettere alla fine. Assicurati di lasciare il suo cervello dietro.
