Code Documentation:The Complete Beginner’s Guide
あなたはあなたの最初のプログラミングの仕事に少しの方法だし、物事は簡単になっています。 最初は、あなたが対処しなければならなかったすべてのコードがあなたを圧倒して混乱させたかもしれませんが、あなたはそれを得始めています。 それは素晴らしいです！ 今、あなたはあなたが次のレベルに書くコードを取る方法を疑問に思っています。 プログラミングスタックについて学ぶことはたくさんありますが、その多くはより良いプログラマになりますが、どのスタックで作業していても役 それらの1つはコード文書です。
多くの開発者は、価値を見ていないか、時間がないように感じるために、十分なドキュメントを書いていません。 あなたはそれらの開発者の一人である必要はありません。 少しの時間と多くの練習をすれば、コードのドキュメントを追加して、あなたと一緒に来る他の人の両方にそれを読むことを喜びにすることができ
良いドキュメントは多くの形で来る
ほとんどの開発者がコードドキュメントを考えるとき、彼らはコメントを考える。 コメントはコードへの貴重な追加になる可能性がありますが、ドキュメントの唯一の定義ではありません。 ドキュメントは、他の誰かがそれがどのように動作するかを理解するのを助けるためにあなたがコードに加えて書くものです。 このようには考えられないかもしれませんが、コードドキュメントの良い例はREADMEファイルです。 基本的なドキュメントの良い例は、Expressです。js READMEファイル。 フレームワークに関するいくつかの重要な質問に答え、プロジェクトにどのように含めることができるか、それをインストールする方法、テストを実行す
良いドキュメントもAPIドキュメントの形で来ることができます。 もう一度、エクスプレス。jsは素晴らしい例を提供します。 このバージョンのドキュメントは、フレームワークを使用する開発者のための参照ライブラリです。 個々の関数が何をしているのか、それらの関数の異なるパラメータが何を意味するのかについての質問への回答を見つけることができます。 その品質のドキュメントがなければ、Expressはそれを使用するチームがほぼ同じくらい多くないでしょう。
もちろん、インラインコメントを使用してコードを文書化することもできます。 これらの種類のコメントは、通常、自分のチームの外の人にコードについて教えるためには使用されません。 代わりに、彼らはあなたのチームメイトやあなたの将来の自己にコードの特定のビットで何が起こっているかを説明するのに便利です。
なぜコードを文書化する必要があるのか
上記のように、多くの開発者はコード文書化の目的を理解していません。 彼らは、良いコードは自己文書化されるべきであり、あなたはそれを説明する必要はないと主張するでしょう。 これらの人々は、一言で言えば、間違っています。 真実は、良いドキュメントはどのコードベースにも不可欠な部分であるということです。 どうして？ なぜなら、それが何をするのかを理解するためにあなたのコードをすべて読む必要はないからです。 その前の文の”人”は、あなたの将来の自己を含む誰を参照することができます。
真実は、多くの場合、それが書かれた後にコードを理解する必要があります”人”はあなたであるということです。 あなたが半年前にそれを書いたときにとても賢いように見えたその少しの論理は、今日理解するのが難しいかもしれません。 あなたのコードが十分に文書化されている場合、それが何をするのかを理解しようとする時間を費やす必要はありません。 あなたは説明を見て数秒を費やすことができるでしょうし、あなたが今取り組んでいるものに戻ることができます。
何十、何百人もの開発者が使用するコードに取り組むのに十分な運が良ければ、良いドキュメントがさらに重要です。 あなたのユーザーの生活は、あなたの時間が良いドキュメントを書くことによって大幅に改善され、彼らはそれをあなたに感謝します。 文字通り！
覚えておくべき重要なことは、良い文書はそれを書くのにかかるよりも時間を節約するということです。 それはあなたの時間かもしれません、またはそれはチームメンバーの時間かもしれません、あるいはあなたが会うこと 時には、ドキュメントを書くことで、複雑すぎるコードの一部を認識するのに役立ち、単純化することができます。
いくつかの一般的なドキュメントの間違い
ジュニア開発者として、あなたはドキュメントを効果的にするものを学ぶ時間を費やす必要があります。 良いニュースは、あなたがよくある間違いを避けることができるように、あなたの前に行ってきた人々から学ぶことができるということです。
Under-Documentation
私がコードドキュメントで見るよくある間違いの一つは、すでにはっきりと見える情報を文書化することです。 たとえば、怠惰な開発者は、関数の名前だけでなく、各パラメータとその個々の型の名前を提供するブロックを追加することにより、関数に”ドキュメント”を追 このタイプのドキュメントは役に立たない！ 誰かが関数の名前とそれが取るパラメータを読むのに数秒かかります。 それはドキュメントではなく、ただの繰り返しです。 代わりに、ドキュメントには、関数が何をするのか、各パラメータが関数の動作をどのように変更するのか、なぜ必要なのかについての簡単な情報を
オーバードキュメント
反対のパターンも深刻な問題になる可能性があります。 あまりにも少ないドキュメントを書くのを避けるために、一部の開発者は、関数に含まれているロジックのすべての小さなビットの説明を書き出 彼らは細心の注意を払って、関数の作成に入ったすべての理論的根拠を文書化します。 それらが完了するまでに、彼らはドキュメントを書いたのと同じくらい長い間関数を書いていたかもしれません。 さらに悪いことに、ドキュメントは理解するのが難しく、コードを読むのと同じくらい長くかかります。 そのような文書化も時間の無駄です。 代わりに、良い文書は、何と理由の両方の基本的な説明を提供します。 理解すべきコードの特に難しい部分がある場合は、ドキュメントでそれらの部分だけを説明する必要があります。
を文書化するためのテストに依存することがあります。 単体テストを読むことは、コード自体を読むことと同じくらい難しいことがよくあります。 あなたのコードが何をしているのかを学びたい開発者は、すべての単体テストを探して読んでいる間に大きな第一歩を踏み出すでしょう。 多くの人は、彼らが何をするために着手したのかを達成する前にあきらめます。 単体テストはどのコードベースにも価値のある追加ですが、優れたドキュメントの代わりにはなりません。
ドキュメントを次のレベルに引き上げる方法
大きなコードベースで作業する場合、特にこの時点までコードを文書化することに熱心ではない場合、コードドキュメントは困難に感じることがあります。 あなたが海を沸騰させようとしているように感じるかもしれません。 大きなコードベースがある場合、または優れた文書化が重要であることがわかっている場合は、自動化されたコード文書化ツールを調査することができま これらのツールは、チーム全体のための一貫性のある、良いドキュメントを書くプロセスを大幅に簡素化します。 GhostDocのようなツールは、インテリジェントにあなたのコードを見て、キーを押すのカップルであなたの文書をキックスタートするためにあなたのチームによっ 自動化されたドキュメントツールは、ドキュメントを書くことに反対する他の一般的な理由の一つを削除します。
一貫性のあるドキュメントがあれば、他のツールを使用すると、そのドキュメントを簡単に共有できます。 自動化されたドキュメントツールは、コードが提供する公開Apiのようなもののための良いドキュメントを開発することから苦痛を取り除きます。
Get Started Today
素晴らしいドキュメントを書くことは、コードを書くよりもはるかに簡単です。 コードとは異なり、ドキュメントは全か無かの企業ではありません。 毎日一つの機能のための良いドキュメントを書くことを目標から始めます。 そのような練習は健全な習慣を構築し、コードベースの一部を理解しようとする時間をはるかに少なくすると、道の下でペイオフが表示されます。 時間が経つにつれて、良いドキュメントを持たないコードを書くと間違っていると感じ始めるでしょう。 コードレビュー中に、同僚にドキュメントを改善する方法を指摘し始めます。 一つの小さな習慣は、あなたのビジネス全体のためにあなたのチームのコードを改善します。
GHOSTDOCがXMLコメントを簡素化し、品質の高いヘルプドキュメントを作成し、維持するのにどのように役立つかを学びます。
著者について
Eric Boersma
Eric Boersmaは、医薬品のITセキュリティから米国政府のためのインテリジェンスソフトウェアの作成、非営利のための国際開発チームの構築 彼は道に沿って学んだことについて話すのが大好きで、他の人からも聞いて学ぶことを楽しんでいます。
