長年にわたり、私はあらゆる種類のプロジェクトに取り組んできました - 大きい、小さな、混沌とした、過剰に設計された、「一時的な」、いわば良好に構造化された、そしてその間のすべて。 The documentation is always missing, outdated, or buried in some forgotten corner of Confluence guarded by a 2019 timestamp. 各プロジェクト 文書を持つこと。 主張 各チーム 彼らはそれを更新するでしょう。 約束 そして、すべての開発者は自信を持って「心配しないでください、私は後で書きます」と言っているドキュメンタリーに等しいことを私たちは知っています。 「チェックは郵便局にあります」。 私が認めたい以上に何度もこのサイクルを繰り返しているのを見た後、私は単純で残酷に真実な何かを実感しました。 
 
 ドキュメンタリーは、できるだけコードに近づいて生きていれば生き残る――なぜなら、開発者(私も含めて)は怠惰な生き物だからだ。 Documentation only survives if it lives as close to the code as possible—because developers (myself included) are lazy creatures. そしてそれから、もう一つの認識が来た - 時代遅れのドキュメントの主な問題は、ほとんどのチームがそれを主な開発サイクルの一部と見なさず、後でそれを残すか、すでに Confluence でどこかで持っていたいくつかのプレデヴの仕様に従うことである。 有意義なドキュメントを書くには、まずソフトウェアコンポーネントのドキュメントの種類について説明しましょう。 Ways to Document Code (That Developers Might Actually Use) ドキュメントコードの方法(開発者が実際に使用できる方法) 文書がコードに近づく必要があると受け入れると、次の質問は を構築する。 どう 実践では、良いドキュメントは単一のアーティファクトではなく、それぞれ異なる目的と観客に奉仕する小さな層の生態系であることを発見しました。 私が言及したプロジェクト(Java + Spring Bootで書かれた)では、ドキュメントの4つの主要なタイプを特定しました。 1. Client Specs これらは通常、ドメイン専門家によって作成された従来の文書です。理想的には、彼らは普遍的な言語で豊富であり、ビジネスケースのコードアグノキシックな記述を提供します - 言い換えれば、エンジニアが実際に問題を理解するために必要なすべてです。 残念ながら、実際には、これらのドキュメントは Confluence でどこかに保存され、プロジェクトの開始時にチームと共有され、その後ほとんど更新されません。 誤解しないでください:この文書 大事な は ドメインの専門家からの知識を抽出することは、あらゆるエンジニアリングチームにとって最優先事項でなければなりませんが、仕様は進化し、期限はすべての人にストレスを与え、それらのオリジナルドキュメントはゆっくりとしかし確実に時代遅れの基盤になります。 変化する要件、エッジケース、プロジェクトピオットの知識は、上級開発者の頭の中でコード(あるいは更に悪い!)に生きる。 これに対処するために、我々は、忘れられるように意図されたランダム Word ファイルや Confluence ページに仕様を書くのをやめ、できるだけ前線に近づいた。 the code repository. レポ内の Markdown (.md) ファイルとして保存し始めました、通常はドキュメント / フォルダに。 大規模なマイクロサービス環境では、これらの文書は、Gitサブモジュールとしてリンクされた専用リポジトリを正当化することもできます。 サブモジュールについてさらに読むには、私はこのブログ記事をお勧めします - . リンク 2. README – The Front Door for Humans クライアントの仕様が百科事典である場合、README はフロントドアであり、それにもかかわらず、ソフトウェアプロジェクトで最も無視されている文書の一つです。 皮肉なことに、ほとんどすべてのバージョンコントロールプラットフォーム - GitHub、GitLab、Bitbucket - は自動的にREADMEをメインプロジェクトページに表示します。これは、開発者がリポジトリに到着したときに最初に見るものです。それにもかかわらず、READMEsはしばしば衝撃的に空っぽで、痛く時代遅れ、または恐ろしい「TODO: 後でドキュメンタリーを書く」で満たされています。 A good README is not optional. It is the single document most likely to actually be read because it requires. 良いREADMEはオプションではありません。 そして、それはレポの根っこに座っているので、開発者はコードの作業中にそれを更新する可能性が高くなります。 zero clicks よく書かれたREADMEは、開発者がプロジェクトに直面する最初の数分以内に持っている最も重要な質問に答えるべきです。 
 
 
 
 
 
 
 このサービス/プロジェクト/コンポーネントは何をしますか? - 簡潔な目的と文脈に関する声明 - マーケティングフローなし。 どのようにローカルで実行しますか? - ランタイム指示、環境変数、依存設定、およびプロジェクト特有のコマンド。 どのようにテストしますか? - ユニットテスト、統合テスト、テストデータセットアップ、およびテスト関連ツール。 プロジェクトの構造は? - ディレクトリのレイアウト、キーモジュール、そしてコードの重要な部分を見つける場所の短い説明。 どのように展開しますか? デプロイス スクリプト、CI/CD ノート、必要な許可、またはプラットフォームのニュアンス。 Where can I read further? - 生成ドキュメント、アーキテクチャノート、API参照、および中央設計文書へのリンク。 README は、プロジェクトへのゲートウェイであり、期待を設定し、オンボード時間を短縮し、すべてのエンジニア(新規または経験豊富)に明確な方向性を与えます。 3. JavaDocs – Docs That The Compiler Annoys You Into Maintaining JavaDocs - 通常、目に見えない、しばしば忘れられているが、何かが壊れたときに絶対に不可欠です。 実際には、Javaプロジェクトのドキュメンタリー化は、しばしば2つの極端に陥る。 あるいは なぜなら、「コードは自己文書化している」 真実は、いつものように、真ん中にあります。 over-commenting every trivial line no comments at all 私たちのプロジェクトのために、我々は書類を書くという意識的な決定を下しました。 その意味: only what was genuinely necessary 
 
 
 
 
 広範囲にわたる言語を使用して、ドメイン用語がビジネス仕様に正確に一致するように コードがすでに明らかにしていることではなく、非明らかな決定の背後にある理由を説明する コアドメインクラス、インターフェイス、および複雑なワークフローの文書化 メソッド名を単に言語形式で繰り返すコメント壁を避ける JavaDocs は、適切に使用すると、コードを混乱させることなく意図を明確にするマイクロレベルの文書として機能します。 
 
 コンパイラは実際に同期されなくなったときに文句を言います。 パラメータの名前を変更したが、JavaDoc タグを忘れた場合は、ビルドがあなたを思い出させます。 メソッドを削除するが、コメントの引用を残すと、IDEはクリスマスツリーのように点灯します。 この柔らかい摩擦は、JavaDocsが他の形式のドキュメントよりも正確である傾向がある理由であり、無視するのが苦手です。 すべてを集中的に維持し、「ドキュメント島」を避けるために、私たちはまた、 . Doxygen Doxygen は、ソフトウェア開発で広く使用される文書生成ツールですが、主に C++ コミュニティで使用されるものの、JavaDocs を一貫した、閲覧可能な参照 - HTML ページにまとめるために使用しました。 これは、分散したIDEヒントに依存することなく、コードベース全体の清潔で統一された視点を提供しました。 4. Clean Code – The Documentation You Don’t Need to Maintain 最後に、最も過小評価されているドキュメントの形態は、開発者が本当に必要になるまで最も尊敬するものである。 clean code. コメントの年齢 スペックは動き回ります. READMEs は無視されます. JavaDocs は停滞する可能性があります. しかし、よく書かれたコード(明確で、意図的で、表現的な)は、 文書化 は ボブおじさんが有名に言ったように、 「クリーンなコードは、よく書かれた小説のように読む」 実践では、これは、 
 
 
 
 
 
 
 目的を明らかにする名前を持つクラスと方法 ひとつのことをする機能と、それをうまくする機能 ドメイン用語は一貫して使われている。 自分の為に賢くない。 内側に隠された「サプライズ行動」 理解するために博士号を必要とする不必要に深い抽象論はない Clean code is the one artifact guaranteed to survive refactors, sprints, staff turnover, and organizational chaos. It is always in sync with the behavior of the system because--it システムの行動について。 is 時間の経過とともに、簡単なルールが私たちに現れた: If you need a paragraph of comments to explain a method, the real problem is the method. コードが表現的になると、他のすべてが簡単になります → JavaDocs が軽くなり、より焦点を当てる → README が縮小します オンボードが明らかになります → ドメインモデルがビジネス辞書を反映しているため、仕様が明確になります。 クリーンコードはドキュメントの必要性を排除するものではありません。 ITです。 アンカー それは、他のあらゆる形式のドキュメント(スペック、READMEs、JavaDocs)が、不明確な実装を補償する代わりに、真実を強調していることを保証します。 結局のところ、クリーンコードは、メンテナンス、CI統合、ツール化を必要としないドキュメントです。 Bringing It All Together — A Living Documentation Pipeline Bringing It All Together - A Living Documentation Pipeline ドキュメンタリー ドキュメントを書く方法を改良した後、最後のステップは、ドキュメントが単に作成されたのではなく、継続的に配信され、常にアクセスできるようにすることでした。 . living documentation portal 私たちはドキュメントが私たちのコードにできるだけ近づくことを望んでいたので、私たちはすべてを展開することにしました。 , which gave us an effortless, version-controlled hosting solution directly tied to the codebase. Github Pages is not particular to Github (GitLab, for example, also has GitLab pages) - it is another clean feature of the popular version control systems I recommend for further reading - Github Pages is not particular to Github (GitLab, for example, also has GitLab pages) - これは、人気のバージョンコントロールシステムのもう一つのきれいな機能です。 . GitHub Pages リンク すべてを一連の一貫したページにまとめるために、我々は Sphinx. Sphinx は Python で書かれた強力なドキュメント ジェネレーターで、reStructuredText または Markdown で書かれたソース ファイルを取り、HTML、PDF、ePub を含むさまざまな出力形式に翻訳します。 Sphinx は、構造、ナビゲーション、およびテーマを処理しました。 Doxygen は、自動生成された JavaDocs を使用して Sphinx を供給しました。 プラグインは、ソースコードから直接完全に閲覧可能なAPI参照を提供します。その間に、Root READMEは、リポジトリを探索する開発者にとって直接の入力ポイントとして機能し、生成された文書サイトにシームレスにリンクします。 呼吸 メインのすべての合併は、ドキュメントを再構築する CI 作業を引き起こし、ポータルが最新のコード変更、API アップデート、設計決定を反映したことを確実にしました。 これにより、私たちのドキュメントは静的なアーティファクトから、開発者が実際に使用した継続的に更新された生態系に変貌し、日々のワークフローに直接統合され、コードと共に生きていました。 Conclusion — Documentation Is Our Responsibility, Not Our Burden 結論 - 文書化は私たちの責任であり、私たちの負担ではありません。 結局のところ、文書を書くことは選択肢ではありません。それはエンジニアリングの専門家としての仕事の一部です。将来のチームメイトはそれに依存します。オンボードはそれに依存します。 ドキュメントをコードに近づけ、自動化できるものを自動化し、Markdown、JavaDocs、Doxygen、Sphinxなどのスマートツールに頼ることにより、通常、ドキュメントの取り組みを殺す摩擦を取り除きます。 ドキュメントは完璧である必要はありません - アクセス可能で正確で活発でなければなりません. 開発者がコードを書くのと同じくらい簡単にドキュメントを更新するよう奨励するシステムを構築すると、誰もが利益を得ます:チーム、製品、そして最も重要なことは、プロジェクトを6ヶ月後に継承する貧しい魂です。 良いドキュメンタリーは私たちを怠慢なものにするのではなく、ただ怠慢であることが素晴らしいソフトウェアを構築することに互換性があるだけです。

The is an opinion piece based on the author’s POV and does not necessarily reflect the views of HackerNoon.

Every

Front

Read My Stories

このオーディオは、ストーリーの元の言語で制作されています。

If your documentation takes two clicks to open, congrats - It is already outdated. ドキュメントを開くには2回のクリックが必要な場合、それはすでに時代遅れです。

About Author

コメント

ラベル

この記事は

Related Stories

目に見えない層: ユーザーインタビューがかけがえのない資産である理由

暗号通貨の成長: 効果的なユーザーペルソナの作成

フォーラムからフィードへ: ソーシャルメディアアルゴリズムがデジタルインタラクションを形作る仕組み

Claude Sonnet 3.5 システムプロンプトの漏洩: 法医学的分析

目に見えない層: ユーザーインタビューがかけがえのない資産である理由

暗号通貨の成長: 効果的なユーザーペルソナの作成

フォーラムからフィードへ: ソーシャルメディアアルゴリズムがデジタルインタラクションを形作る仕組み

Claude Sonnet 3.5 システムプロンプトの漏洩: 法医学的分析

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps