昨年、支払いゲートウェイをハッキングしたのはハッカーではありませんでしたが、DDoS攻撃やメモリ漏洩ではありませんでした。 デイブだった。 さて、具体的には、デイヴがヴェルモントのヤギ農場に引っ越すことを決意し、15000行のスパゲッティコードを残して、我々の繰り返しの請求論理全体を処理しました。 この役に立つコメントを見つけました: BillingService.js // TODO: Fix this hack later. It's ugly but it works. - Dave, 2019 パラメータの定義はありません. 返却タイプはありません. なぜライン405が変数と呼ばれるものによって分割されているのかの説明はありません。 我々は3日間、顧客が騒いでいる間に、自社の製品をリバウンドエンジニアリングすることに費やした。 magicNumber We treat code documentation like flossing: we know we 私たちは歯医者(マネージャー)に嘘をつきますが、事態が腐り始めるときにしか実際にそうしません。 すべき しかし、あなたがそれを書く必要がなかったらどうでしょうか? 10年の経験を持つテクニカルライターがあなたの隣に座り、暗号化されたPythonスクリプトを数秒で原始的でスフィンクス準備のドキュメントに変えることができますか? I stopped expecting developers to be poets. 私は開発者が詩人であることを期待するのをやめた。 . Agentic Documentation Strategy 「Write-Only」コードベースの流行 ほとんどのAI生成ドキュメンタリーはフラフです. You ask ChatGPT to "document this," and it gives you: def process_data(data): """ Processes the data. """ ロボットさん、有難うございました。 実際のドキュメンタリーは、夜に目覚めさせ続ける質問に答える必要があります。 この入力が null であればどうなるのでしょうか? なぜこの関数はグローバル変数に依存するのでしょうか? 返されるオブジェクトの特定の形式は何ですか? 2 得る 詳細のレベルで、AIを維持者ではなく、サミュレータのように考えるように強制する必要があります。 それは、LLMが分析することを強要する。 コードではなく、シンタクスだけ。 あの Code Documentation System Prompt 意図 The Technical Writer System Prompt(テクニカル・ライター・システム・プロンプト) 私はこのプロンプトを Claude または ChatGPT に挿入し、私の機能をダウンロードし、Google が維持するライブラリに属しているように見える文書を取り戻します。 あなたの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 Why This Works (When "Please Document This" Fails) このプロンプトは、AIの「精神モデル」を偶然のチャットから厳格なアーカイブに変えるため、機能します。 1.「使用例」の命令 見る The ポイント: ドキュメンタリーが教えてくれる Code does. Examples tell you. コード does. 例が教えてくれる AI を動作例を生成するように強制することにより、AI がコードの実行をシミュレートすることを強制し、それらが質問される前に「どうやってこれを呼ぶか?」という質問の 80% を解決します。 Quality Checklist 少なくとも1つの使用例が提供されます。 何 どう 2.エッジケースの発掘 A Junior Dev はこう書いている。 このスピーチは、AIに書くことを強要します: 明示的に求めているのは、 そして 暗示的な仮定(「明らかに日付は無効ではない」)を明示的な契約に変える。 @param {string} date @param {string} date - ISO 8601 format (YYYY-MM-DD). Throws ValidationError if past date. Parameter Constraints Error Handling 「バス・ファクター」の保険 THE セクションは機能名の再定義だけではありません。それは「目的の高いレベルの概要」を必要とします。これはデイヴが彼と一緒にヤギ農場に連れて行った文脈です。 しかも, not only the . Overview なぜ 何 Leave a Legacy, Not a Mystery(謎ではなく遺産を残す) あなたがドキュメンタリーのないコードを押すとき、あなたは時間を節約するのではなく、あなたはあなたの将来の自分(またはあなたの貧しいチームメイト)が莫大な利息で返済しなければならない融資を受け取っています。 あなたはドキュメントを書くことを愛する必要はありません. あなたは単に専門家にそれを処理するのに十分に賢い必要があります。 コピーしてコードを入力してください チームを保存してください 「デイヴ」はついに辞めようとしているので、彼の脳を後ろに置いておくようにしてください。
