To nie był atak DDoS ani wyciek pamięci. To był Dave. Cóż, w szczególności faktem było, że Dave zdecydował się przenieść się do farmy kozy w Vermont, pozostawiając za sobą 15 000 linii kodu spaghetti, który obsługiwał całą naszą logikę powtarzających się rozliczeń. Znalazłem ten przydatny komentarz: BillingService.js // TODO: Fix this hack later. It's ugly but it works. - Dave, 2019 Brak definicji parametrów Brak typów zwrotów Brak wyjaśnienia, dlaczego linia 405 była podzielona przez zmienną o nazwie Spędziliśmy trzy dni na inżynierii odwrotnej naszego własnego produktu, podczas gdy klienci szarżowali. magicNumber Dokumentację kodową traktujemy jak flossing: wiemy, że Jeśli to zrobimy, kłamiemy naszym dentystom (zarządzającym) o tym, ale tak naprawdę robimy to tylko wtedy, gdy rzeczy zaczynają się gnić. Powinien Co by było, gdybyś mógł mieć Technical Writer z 10-letnim doświadczeniem siedzącego obok ciebie, przekształcając swoje kryptyczne skrypty Python w oryginalną, gotową do Sphinx dokumentację w kilka sekund? Przestałem oczekiwać, że deweloperzy będą poetami. . Agentic Documentation Strategy Epidemia „tylko pisemnej” bazy kodów Większość dokumentacji generowanej przez AI jest fluff.Prosisz ChatGPT o „dokumentowanie tego”, a to daje: def process_data(data): """ Processes the data. """ Dziękuję, Robot bardzo mi pomoże. Prawdziwa dokumentacja musi odpowiedzieć na pytania, które utrzymują cię w nocy: Co się stanie, jeśli ten wpis jest null? Dlaczego ta funkcja zależy od zmiennej globalnej? Jaki jest konkretny format obiektu zwrotnego? Dostać się poziom szczegółów, musisz zmusić AI do myślenia jak konserwator, a nie podsumowujący. Oznacza to, że LLM analizuje Kod, a nie tylko syntax Tego Code Documentation System Prompt intencji Techniczny system pisarski Prompt Wklejam tę wskazówkę do Claude'a lub ChatGPT, włącz moją funkcję i otrzymuję dokumentację, która wygląda, jakby należała do biblioteki obsługiwanej przez Google. Zostań częścią swojej listy kontrolnej 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 Dlaczego to działa (gdy "Please Document This" nie działa) Ta wskazówka działa, ponieważ zmienia "model umysłowy" sztucznej inteligencji z przypadkowego rozmówcy na rygorystycznego archiwisty. Mandat „Usage Example” Spójrz na The W punkcie: Dokumentacja mówi Przykłady mówią, przykłady mówią Zmuszając sztuczną inteligencję do generowania przykładu pracy, rozwiązujesz 80% pytań "jak to nazwać?" zanim zostaną nawet zapytane. Quality Checklist Przykładowe zastosowanie przynajmniej jednego co jak • Edge Case wykopalisk A junior dev pisze: Ta prędkość zmusza AI do pisania: Wzywa wyraźnie do i Przekształca domniemane przypuszczenia ("oczywiście data nie może być nieważna") w wyraźne umowy. @param {string} date @param {string} date - ISO 8601 format (YYYY-MM-DD). Throws ValidationError if past date. Parameter Constraints Error Handling Ubezpieczenie „Bus Factor” o sekcja to nie tylko ponowne określenie nazwy funkcji. Wymaga to "podsumowania celu na wysokim poziomie." To jest kontekst, który Dave zabrał ze sobą do gospodarstwa kozy. Nie tylko te . Overview Dlaczego co Zostaw spuściznę, a nie tajemnicę Kiedy naciskasz na niedokumentowany kod, nie oszczędzasz czasu; pobierasz pożyczkę, którą twoje przyszłe ja (lub twoi biedni koledzy z zespołu) będą musieli spłacić z ogromnym odsetkiem. Nie musisz kochać pisania dokumentów, po prostu musisz być wystarczająco sprytny, aby pozwolić specjalistom poradzić sobie z tym. Kopiuj polecenie. Wstaw kod. Zapisz zespół. Ponieważ "Dave" ostatecznie zrezygnuje. upewnij się, że zostawił za sobą swój mózg.
