
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 長年にわたり、私は大小さまざま、混沌とした、過剰に設計された、「一時的な」、一見うまく構成されたものまで、あらゆる種類のプロジェクトに取り組んできました。それにもかかわらず、一つのパターンが驚くほど一貫しています。 ドキュメントは常に欠落しているか、時代遅れになっているか、あるいは2019年のタイムスタンプに守られたConfluenceの忘れられた片隅に埋もれているのです。 すべてのプロジェクトはドキュメントがあると 。 主張します すべてのチームはそれを最新の状態に保つと 。 約束します そして、すべての開発者は自信を持って「心配しないで、後で書くよ」と言いますが、それは私たち全員が知っているように、ドキュメントにおける「 」と言うのと同じことです。 小切手は郵便で送った このサイクルが何度繰り返されたか数えきれないほど見た後、私はシンプルでありながら非常に真実なことに気づきました。 
 
 ドキュメントは、コードのできるだけ近くに存在しないと生き残りません。なぜなら、開発者（私自身を含めて）は怠惰な生き物だからです。 そしてそこから、もう一つの気づきがありました。時代遅れのドキュメントの主な問題は、ほとんどのチームがそれを主要な開発サイクルの一部と見なしておらず、後回しにしたり、どこかConfluenceにあった開発前のいくつかの仕様で済ませてしまったりする事実です。 意味のあるドキュメントを書くために、まずソフトウェアコンポーネントにはどのような種類のドキュメントがあるかを議論しましょう。 開発者が実際に使用する可能性のあるコードのドキュメント化の方法 ドキュメントがコードの近くに存在しなければならないことを受け入れたら、次に問題となるのはそれをどのように構造化するかということです。 実際には、優れたドキュメントは単一の成果物ではなく、それぞれ異なる目的と対象者に役立つ層の小さなエコシステムであることがわかりました。 私が言及したプロジェクト（Java + Spring Bootで書かれた）では、4つの主要なドキュメントタイプを特定しました。 1. クライアント仕様 これらは通常、ドメインエキスパートによってコンパイルされる従来のドキュメントです。理想的には、それらは普遍的な言語に富み、ビジネスケースのコードに依存しない説明を提供します。つまり、エンジニアが直面している問題を真に理解するために必要なすべてです。 残念ながら、実際には、これらのドキュメントはしばしばConfluenceのどこかに保存され、プロジェクトの開始時にチームと共有され、その後ほとんど更新されなくなります。 誤解しないでください：これらのドキュメントは です。 重要 ドメインエキスパートからの知識の抽出は、あらゆるエンジニアリングチームにとって最優先事項であるべきです。しかし、仕様は進化し、締め切りは皆をストレスにさせ、それらの元のドキュメントはゆっくりとしかし確実に時代遅れになります。 変更された要件、エッジケース、プロジェクトの方向転換に関する知識は、コードの中、あるいはさらに悪いことに、シニア開発者の頭の中に残ることになります。 これを解決するために、私たちはランダムなWordファイルや忘れられる運命にあるConfluenceページに仕様を書くのをやめ、それらを最前線にできるだけ近づけました： コードリポジトリです。 私たちはそれらをリポジトリ内のMarkdown（.md）ファイルとして保存し始めました。通常はdocs/フォルダ内です。 大規模なマイクロサービス環境では、これらのドキュメントは専用のリポジトリをGitサブモジュールとしてリンクすることを正当化することさえあります。サブモジュールはしばしば見過ごされますが、マルチリポジトリエコシステムを整理するための強力な方法です。 サブモジュールに関するさらなる読書については、このブログ投稿を強くお勧めします -  。 リンク 2. README – 人間のための玄関ドア クライアント仕様が百科事典なら、READMEは玄関ドアです。それにもかかわらず、ソフトウェアプロジェクトで最も見過ごされているドキュメントの1つです。 皮肉なことに、ほとんどすべてのバージョン管理プラットフォーム（GitHub、GitLab、Bitbucket）は、リポジトリのメインページでREADMEを自動的にレンダリングします。リポジトリにアクセスした開発者が最初に目にするものです。それにもかかわらず、READMEはしばしば驚くほど空であったり、痛々しいほど時代遅れであったり、「TODO：後でドキュメントを書く」という恐ろしいもので埋め尽くされていたりしますが、もちろんそれは決して起こりません。 優れたREADMEはオプションではありません。それは、 で済むため、実際に読まれる可能性が最も高い単一のドキュメントです。そして、リポジトリのルートにあるため、開発者はコードを操作しながらそれを更新する可能性が高くなります。それは最小抵抗のパスにあるドキュメントです。 クリックがゼロ 適切に書かれたREADMEは、開発者がプロジェクトに遭遇した最初の数分で抱く最も重要な質問に答えるべきです。 
 
 
 
 
 
 
  簡潔な目的とコンテキストの記述 - マーケティングの誇張なし。 このサービス/プロジェクト/コンポーネントは何をするのか？ -  ランタイム命令、環境変数、依存関係の設定、およびプロジェクト固有のコマンド。 ローカルで実行するにはどうすればよいか？ -  単体テスト、統合テスト、テストデータの設定、およびテスト関連のツール。 テストするにはどうすればよいか？ -  ディレクトリレイアウト、主要モジュール、およびコードの重要な部分を見つける場所に関する簡単な説明。 プロジェクトはどのように構造化されているか？ -  デプロイメントスクリプト、CI/CDの注記、必要な権限、またはプラットフォームのニュアンス。 デプロイするにはどうすればよいか？  生成されたドキュメント、アーキテクチャノート、APIリファレンス、および集中化された設計ドキュメントへのリンク。 さらに読むにはどこか？ - READMEはプロジェクトへの入り口です。それは期待を設定し、オンボーディング時間を短縮し、すべてのエンジニア（新規または経験豊富）に明確なオリエンテーションポイントを提供します。適切に維持されると、それはリポジトリ全体で最も価値のある単一のドキュメントになります。 3. JavaDocs – コンパイラが維持するようにあなたを悩ませるドキュメント JavaDocs – 通常は目に見えず、しばしば忘れられますが、何かが壊れたときには絶対に不可欠です。 実際には、Javaプロジェクトのドキュメント化はしばしば2つの極端に陥ります。すなわち、 か、あるいは「コードは自己文書化されている」という理由で かのどちらかです。真実は、いつものように、その中間にあります。 すべての些細な行を過剰にコメントする 全くコメントしない 私たちのプロジェクトでは、 をドキュメント化するという意識的な決定を下しました。それは意味しました。 本当に必要なものだけ 
 
 
 
 
 ドメイン用語がビジネス仕様と正確に一致するように、 を使用すること 普遍的な言語 コードがすでに明らかにしていることではなく、明白でない決定の を説明すること 理由 コアドメインクラス、インターフェース、および複雑なワークフローをドキュメント化すること メソッド名を冗長な形式で繰り返すだけのコメントの壁を避けること JavaDocsは、適切に使用されると、コードを乱雑にすることなく意図を明確にするマイクロレベルのドキュメントとして機能します。そして、Confluenceページとは異なり、JavaDocsには組み込みの利点があります。 
 
 同期が取れなくなると、コンパイラが実際に文句を言います。 パラメータをリネームしてもJavaDocタグを忘れた場合、ビルドが通知してくれます。 メソッドを削除しても古いコメント参照を残した場合、IDEはクリスマスツリーのように点灯します。 この穏やかな摩擦こそが、JavaDocsが他の形式のドキュメントよりも正確である傾向がある理由です。無視するのは迷惑だからです。 すべてを一元化し、「ドキュメントの孤島」を避けるために、私たちは も使用しました。 Doxygen Doxygenは、ソフトウェア開発で広く使用されているドキュメントジェネレータツールです。主にC++コミュニティで使用されていますが、JavaDocsをHTMLページとして一貫性があり、ブラウズ可能なリファレンスに集約するために使用しました。JavaDocにはない多くの機能、例えば階層のクラス図や協力コンテキスト、より多くの概要ページなどがあります。 これにより、散在するIDEヒントに依存することなく、コードベース全体のクリーンで統一されたビューが得られました。 4. クリーンコード – 維持する必要のないドキュメント 最後に、最も過小評価されている形式のドキュメントであり、必要になるまで開発者が最も尊敬しないものです。それは です。 クリーンコード コメントは古くなります。仕様は逸脱します。READMEは無視されます。JavaDocsは時代遅れになります。 しかし、よく書かれたコード – 明確で、意図的で、表現力のあるコード – はドキュメント 。 です Uncle Bobが有名に言ったように、「 」 クリーンコードはよく書かれた散文のように読める そして実際には、それは意味します。 
 
 
 
 
 
 
 目的を明らかにする名前を持つクラスとメソッド 一つのことをうまくこなす関数 ドメイン用語が一貫して使用されていること 単なる巧妙さではない 副作用に隠された「予期せぬ動作」がないこと 博士号が必要なほど深く理解する必要のない、不必要に深い抽象化がないこと クリーンコードは、リファクタリング、スプリント、人員の入れ替わり、組織の混乱を乗り越えることが保証されている唯一の成果物です。それはシステムの動作と常に同期していますが、なぜならそれは です。 システムの動作だから 時間とともに私たちにとってシンプルなルールが生まれました。 メソッドを説明するために1段落のコメントが必要な場合、本当の問題はそのメソッドです。 コードが表現力豊かになると、他のすべてが容易になります → JavaDocsはより軽量で焦点を絞ったものになります → オンボーディングが明白になるためREADMEは縮小します → ドメインモデルがビジネス語彙を反映するため仕様はより明確になります。 クリーンコードはドキュメントの必要性をなくすわけではありません。それはそれを します。 固定 それは、仕様、README、JavaDocsなど、他のすべての形式のドキュメントが、不明瞭な実装を補うのではなく、真実を強化することを保証します。 結局のところ、クリーンコードはメンテナンスも、CI統合も、ツールも必要としないドキュメントです。それはシステムが実際に何をするのかについての最も正直で信頼できる説明です。 すべてをまとめる – 生きたドキュメントパイプライン ドキュメントの書き方を改善した後、最終ステップは、それが作成されるだけでなく、継続的に配信され、常にアクセス可能であることを保証することでした。そのために、仕様、READMEファイル、JavaDocsを、単一の統一された に変換するドキュメントパイプラインを構築しました。 生きたドキュメントポータル ドキュメントをコードのできるだけ近くに置きたかったので、すべてを からデプロイすることにしました。これにより、コードベースに直接関連付けられた、手間のかからない、バージョン管理されたホスティングソリューションが得られました。Github PagesはGithubに限定されません（例えば、GitLabにはGitLab Pagesもあります）。これは、私がさらに読むことをお勧めする一般的なバージョン管理システムのもう一つの便利な機能です -  。 GitHub Pages リンク すべてをまとまりのある一連のページにコンパイルするために、私たちは を使用しました。 Sphinx SphinxはPythonで書かれた強力なドキュメントジェネレータです。reStructuredTextまたはMarkdownで書かれたソースファイルを取り込み、HTML、PDF、ePubなど、さまざまな出力形式に変換します。 Sphinxは構造、ナビゲーション、テーマを処理しました。Doxygenは、 プラグインを使用して自動生成されたJavaDocsをSphinxにフィードし、ソースコードから直接完全にブラウズ可能なAPIリファレンスを提供しました。一方、ルートREADMEは、リポジトリを探索する開発者にとって即時のエントリポイントとして機能し、生成されたドキュメントサイトにシームレスにリンクしました。 Breathe mainへのすべてのマージは、ドキュメントを再構築するCIジョブをトリガーし、ポータルが最新のコード変更、API更新、および設計決定を反映することを保証しました。何も孤立して存在しませんでした。手動同期を必要とするものはありませんでした。そして決定的に、クリック一つでアクセスできないものはありませんでした。 これにより、ドキュメントは静的な成果物から、開発者が実際に使用する継続的に更新されるエコシステムへと変わり、それは日常の開発に直接統合され、コードのすぐ隣に配置されました。 結論 – ドキュメントは私たちの責任であり、負担ではありません 結局のところ、ドキュメントを書くことはオプションではありません。それはエンジニアリングプロフェッショナルとしての私たちの仕事の一部です。将来のチームメイトはそれに依存しています。オンボーディングはそれに依存しています。メンテナンス、信頼性、さらにはアーキテクチャの明確さもそれに依存しています。しかし、その責任を受け入れることが、ドキュメントが苦痛でなければならないという意味ではありません。 ドキュメントをコードの近くに保ち、自動化できるものはすべて自動化し、Markdown、JavaDocs、Doxygen、Sphinxのようなスマートなツールに頼ることで、ドキュメントの取り組みを通常殺してしまう摩擦を取り除きます。私たちは、伝統的に面倒に感じるものを、日常の開発の自然な拡張へと変えます。そして、それにクリーンコード、優れたREADME、そしてドメインに富んだ仕様を組み合わせると、エコシステム全体が自己維持可能になります。 ドキュメントは完璧である必要はありません – ただアクセス可能で、正確で、生きている必要があります。開発者がコードを書くのと同じくらい簡単にドキュメントを更新できるシステムを構築すると、チーム、製品、そして最も重要なことに、6か月後にプロジェクトを引き継ぐ哀れな魂など、すべてが恩恵を受けます。 優れたドキュメントは私たちを怠惰にしなくしません。それはただ怠惰であることを素晴らしいソフトウェアの構築と互換性があるようにするだけです。

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

Read My Stories

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

ドキュメントを開くのに2クリックかかる場合、おめでとうございます。それはすでに時代遅れです。

About Author

コメント

ラベル

この記事は

Related Stories

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

AI の力を解き放つ。最先端技術の体系的レビュー: 概要と序論

フロキのヴァルハラがインドのスリランカツアーのアソシエイトスポンサーに加わる

AI/ML データレイクのリファレンスアーキテクチャを構築するためのアーキテクトガイド

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

AI の力を解き放つ。最先端技術の体系的レビュー: 概要と序論

フロキのヴァルハラがインドのスリランカツアーのアソシエイトスポンサーに加わる

AI/ML データレイクのリファレンスアーキテクチャを構築するためのアーキテクトガイド

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps