documentation - プライベートメソッドを文書化する必要がありますか?

Question

プライベートメソッドのドキュメントは、ソースコードにアクセスできる人だけが見ることができます。それに費やした労力に見合う価値はありますか？

score 78 · Accepted Answer

個人的にはそうだと感じています。多くの場合、ドキュメントは、ソフトウェアを保守する将来の開発者にとって最も役立ちます (特にメンバードキュメント)。

パブリック API ドキュメントでさえ、開発者以外の対象者には限定された用途しかありません。以下の人々のための文書 - 彼らはあなたに感謝します.

score 15 · Accepted Answer

間違いなくそうです。些細なソフトウェア以外の場合は、コメントを適切に使用することで、数か月後の元の作成者であっても、コードをより速く理解できます。

score 14 · Accepted Answer

実装のドキュメントが不要になるように、わかりやすくするためにコードをリファクタリングする必要があります。

そもそも明らかなコードを書くのを怠けるために、コードにコメントする能力を利用しないでください。

コードと同じことを別の言語で記述しているドキュメントは冗長です。また、冗長コードと同様に、この冗長性も維持する必要がありますが、維持されていないことがよくあります。

score 11 · Accepted Answer

はいはいはい。記述したコードを文書化します。

最終的には、あなたが書いたコードを誰かが保守することになります。ドキュメンテーションは、その特定のコードを書くときに持っていた考え方を彼らが理解できるようにするための方法です。プライベート関数は、開発者が不変条件を推測できるコード内での使用量が最も少ない傾向があるため、文書化することが特に重要です。

score 8 · Accepted Answer

はい、間違いなく。6 か月後には、戻ってきてメンテナンスを行う必要がある場合があります。適切に配置されたいくつかのコメントにより、多くの時間と労力を節約できます。公開 API の場合ほど文書化する必要はないかもしれませんが、いくつかのコメントが害になることはありません。

score 7 · Accepted Answer

興味深く、かつ自明ではないほど複雑なことを行うメソッドは、時間をかけてドキュメントで明確にする価値があります。

score 6 · Accepted Answer

私はしません。プライベートメソッドにドキュメントが必要な場合は、この領域でコードをよりクリーンにするために時間を費やす価値があるかもしれません。

編集：要約があっても、私は文書化しません。プライベートメソッドは変更、新たな芽生え、消滅する可能性があります。OO の基本原則の 1 つはカプセル化です。プライベートメソッドが何をしているかを知る必要はありません。開発者に関して言えば、このすべてのドキュメントを最新の状態に保つのは誰ですか? 初めてだけどこれから？

編集2：コメントから

私は強く反対します。プライベートメソッドを (なんらかの方法で) 文書化してはならないのは、その名前とソースコードからその目的が完全に明らかな場合だけです。あなたのコードに何か「賢い」点がある場合は、なぜそのようにしているのかを説明するコメントが必要です。

私は強く同意しますが..コードは「賢い」ものであってはならず、コードは機能的で読みやすいものでなければなりません。ほとんどの場合、コードが読者に対して可能な限り透過的であるようにする必要があります。コメントする必要がある場合は、javadoc (または使用するもの) にアクセスする前に、コードをより明確にすることを検討する必要があります。

編集3：

? むしろ何を見たいですか。

/**
*   This method doesn't do what you expect it to.
*   Below you will find a whole ream of impenetrable
*   code. Where there are bits that look that they do x, they don't
*   they do y. 
**/
private void someComplexInternalMethod()
{
     ...
     badly named variables
     comments to describe intent
     perhaps some out of date orphaned comments
     as code has been removed but comment remains

     ....
     ....
     looong methods 
}

private void WellNamedMethod()
{
     ...
     well named variables
     shorter method, highly cohesive
     self documenting
}

score 4 · Accepted Answer

今から 6 か月後に自分のプライベートメソッドにアクセスしたとき、それらは今と同じようにあなたにとって意味のあるものになりますか? コンポーネント間の関係を追跡するのに何時間も費やす必要がありますか?

私の経験では、優れたドキュメント作成は決して時間の無駄ではありません。

score 4 · Accepted Answer

絶対。コードは常に、2 年後に変更が必要になることを想定して記述してください。メソッドの概要は、すべての中で最も重要です。ドキュメント (要約、引数、戻り値) を書いていて、何かを見逃していることに気付いたので、何度バグを見つけたかわかりません。

score 3 · Accepted Answer

私は不人気な立場を取り、ノーと言います。

そうしないと、私のプライベートメソッドの多くは、メソッド内の複雑なステートメント、つまりコメントが必要なステートメントになります。それらをプライベートメソッドにする理由の半分は、コードを明確にし、その動作を文書化する必要性を減らすことです。

コードが変更されるたびに、ドキュメントを維持および更新する必要があります。あなたは今、保守開発者に同じ作業を 2 回依頼しています。バグを修正するために 1 回、修正について説明するために 1 回。

私の経験では、2 番目のアクションはしばしば発生しません。ここで始めたとき、私は 5 年以上前のコードベースを継承しました。ある特定のアプリでは、すべての約半分がコメントされていました。多くの場合、非常に多くの場合、コメントは実際のコードとほとんどまたはまったく似ていませんでした。彼がそれらを書いたときに酸っぱい人だったか、コードの最初のカットでコメントを書いた後、コードが変更され、コメントが変更されませんでした。

今、私は彼のコメントを読まずに引き出しています。各アプリ、または大規模なアプリ内の論理モジュールには、その一般的な目的、一般的な構造、および通常とは異なるものについて概説する 1 ページまたは 2 ページのドキュメントがあります。

私たちは、開発者が読みやすいコードを書けること、そして新入社員が読みやすいコードを読めることを期待しています。

さぁ、反対投票を始めましょう！

score 3 · Accepted Answer

はい、プライベートメソッドを文書化する必要があります。より多くの開発者がコードを使用し、コードを変更するにつれて、ますます必要になります。プライベートメソッドは、パブリックメソッドと同様に特定の機能を保証します。違いは、コードの使用方法です。プライベートメソッドのドキュメントは、将来のリファクタリングを加速します。

score 3 · Accepted Answer

パブリックメソッドを文書化することは、メンテナーとパッケージを使用する人々の両方に役立ちます。

プライベートメソッドを文書化することは、メンテナーまたはパッケージ (あなたを含む) にとって役立ちます。

要するに、少し異なる方法で必要です。たとえば、プライベートメソッドのドキュメント化は形式的である必要はありません。

score 1 · Accepted Answer

個人的には、コードドキュメンテーションよりも自己文書化コードの方が重要だと考えています。意図を明らかにする名前、副作用のない関数などの多用。

しかし、コードをセルフドキュメンタリーにすることができない場合もあります。その場合は、常に関数または内部の仕組みをドキュメント化します。

score 0 · Accepted Answer

最近、私はコードを始める前にクラス/メソッドレベルのドキュメントを書くことがよくあります。これは、クラスを明確に定義し、メソッドを単一目的に保つのに特に役立ちます。これは、クラス/メソッドが本来の意図を超えて進化したときに通知するリマインダーが目の前にあるためです。

私はコードを書くことができる他の誰よりもドキュメントを書くのが好きではありませんが、あなたがやろうとしていることを自分自身に説明する行為はすべて改善することであるため、コーディング/デバッグの時間がかかるとは思いません。あなたの思考時間からの出力。

メソッドコメントは、便利なダブルチェックも提供します。コードがコメントの内容を実行しない場合は、デバッグ時に調べる価値があるためです。

コードリーダーの観点からは、有用なコードは書かれているよりも何百回も何千回も読み取られるため、コードコントラクトを文書化するコメントにより、リーダーはコードが次の詳細レベルで何をするかを理解する必要がなくなります。何千行ものコードを速読している場合、これにより、高価なメンタルコンテキストを速読から分析に切り替えたり、元に戻したりする必要がなくなります。

仕事の大部分を大量のコードの読み取りに費やすのは、システムの動作を維持し、開発チームに代わって経営陣と交渉する責任があるチームリーダーとアーキテクトです。よく書かれたコードでさえ、その大部分は読者が興味を持っているレベルとは異なる抽象化レベルにあるため、すばやく大量に読むことは困難です。

開発チームを代表する人々がコードをすばやく読むことができない場合、マネージャーと証拠に基づいた話し合いを行うことは困難であり、技術的な現実に影響されることなく意思決定が行われます。

これを何度も繰り返すと、開発チームにとって難しい問題が発生します。これは、詳細なレベルで少しのエンジニアリング規律を適用することで回避できたはずです。

すべてのシステムが大きく、複雑で、答えを知っているだけの教祖が不足しているわけではありませんが、一部のシステムはそのようなものであり、突然そのようになる可能性があります。次世代のトレーニング中の教祖は、コードを文書化してくれてありがとうございます。

score 0 · Accepted Answer

（コンセンサスに反して）私は自己文書化コードを強調します（公開ではなく非公開）。これは非常に効果的であり、正式に文書化する必要はほとんどありません。一部の人々はこれを本当に嫌います（時には正当な理由があります）。プライベートな実装について言及しているので、時間の経過とともに名前を変更して変更するという制約ははるかに少なくなります。少数の特殊なケースを伴うインターフェースは失敗のレシピです (それでも、それらはまだ生成されています)。

ドキュメンテーション: ヘッダーの大部分を消費する場合は、意味のあるものにする必要があります。

インターフェイスと同様に、悪いに勝るものはないため、悪い/無意味なドキュメントをザッピングする習慣があります。へへ

score 0 · Accepted Answer

プライベートフィールドはどうですか？Serializable クラスの場合、プライベートフィールドを文書化する必要があります。Johsua Bloch 著「Effective Java」より:

プライベートフィールドは、クラスのシリアル化された形式であるパブリック API を定義します。このパブリック API は文書化する必要があります。@serial タグの存在により、Javadoc ユーティリティは、シリアル化されたフォームを文書化する特別なページにこの文書を配置するように指示されます。

score 0 · Accepted Answer

パブリックインターフェイス (パブリックメソッドやクラスなど) については、各メソッドの目的を文書化します。パブリックインターフェイス (つまり、コードコントラクト) をできるだけ明確に記述します。

プライベートメンバー (実際に作業を行う場所) については、メソッドの目的を文書化することをお勧めします。しかし、コードの説明だけでなく、なぜ、どのように、アルゴリズムを文書化する方がはるかに便利です。

プライベートメンバーにアクセスできる将来の開発者は、コードにもアクセスできます。あなたのコードを読むことができれば、それが何をしているのか理解できます。しかし、私があなたの考えを読むことができない限り、あなたのコードが何をしているのかを理解する方法はありません.

score 0 · Accepted Answer

メソッド名がその目的をすぐに明らかにしない場合、適切な名前が付けられていません。よく名前が付けられたクラスとメソッドよりもドキュメントに依存すると、必ず戻ってきます。ドキュメントを更新するのを忘れている人が数回いるだけで、ひどい混乱に陥ります。例：

悪い

private void Update(string sValue, DateTime dValue)
{...}

より良い

private void UpdateEmployeeInformation(string jobTitle, DateTime hireDate)
{...}

文書化が必要な 2 番目のバージョンについてはどうですか? 名前はその目的を識別し、パラメーター名は何が渡されると予想されるかを明確にします。

メソッドが非常に長く複雑で、説明するのに小説が必要な場合は、適切な名前を付けて高度に焦点を絞った論理的な機能に分割する必要があります。それ、IMHOは、最新である場合とそうでない場合がある、不十分に書かれたインラインドキュメントよりもはるかに理解しやすいです-すべてのコードを読んで、ドキュメントがすべきことと一致していることを確認し、ほとんどの場合、ドキュメントは維持されていないと仮定して無視します。

また、コードを変更して機能をより明確にする単体テストも必要です。適切な名前のクラス、メソッド、単体テストでは、追加のドキュメントはどのような目的に役立ちますか?

score 0 · Accepted Answer

はい。私が聞いたこの冗談として：

プログラミングはセックスのようなものです。1つの間違いで、残りの人生でそれをサポートする必要があります.

score 0 · Accepted Answer

ええと、そのコードも保守可能でなければなりませんね。もちろん、それらは文書化されるべきです！数か月以内にそのコードに目を通す必要があり、変更を加えるときに参照する何かが必要になるでしょう。

score 0 · Accepted Answer

0

やるべきことが何もない場合にのみ。したがって - おそらく - いいえ。

于 2009-11-16T18:09:59.383 に答える

documentation - プライベート メソッドを文書化する必要がありますか?

21 に答える 21

Related

Reference

documentation - プライベートメソッドを文書化する必要がありますか?