コード ドキュメントに関しては、通常、コードはそれ自体を説明する必要があり、インライン コード ドキュメント (パブリック API ドキュメントを除く) は、回避策、特定の実装が選択された理由の説明などのメタコードの問題のみを説明する必要があることが認められています。
コードをより読みやすく、より説明しやすくするにはどうすればよいでしょうか?
Jeff Atwood のCode Smellsブログ投稿をチェックしてください。それはかなりそれを要約しています。読みやすいコードに関しては、私の個人的な精神を追加します。
/* finished */直前のコメントのようにreturn true;)。適切な変数名とメソッド名を使用してください。コードを特定の目的を達成する意味のある部分に分割します。クラスのまとまりを保ち (すべてが連携して動作する)、切り離された状態を保ちます (クラス間の依存関係はほとんどありません)。繰り返さないでください (DRY)。ボブおじさんのSOLID の原則(彼が指摘するように、法律ではない) に、コードをより良くするために働く程度まで従ってください。
「uncle bob」の book clean code は、関数がどのように見えるべきかのかなり良い概要を、実践的な例で示しています。
いくつかの重要なポイント:
この本にはもっと小さなルールがたくさんあります。私は本当にそれをお勧めします。Code Complete 2 も入手してください。
自己文書化コードは次のとおりです。
ただし、最も自己文書化されたコードでさえ、そこにあるものしか文書化できないことを忘れないでください。意図的に省略したり、最適化したり、試行錯誤したりといったことは決してありません。基本的に、ソース ファイルに英語が必要になることは常にあります。そうしないと、重要な注意事項や設計上の決定を省略せざるを得なくなります。
私は通常、コード内でコメントすることはしませんが、読みやすいコードを書くだけでドキュメントは必要ないというよくある意見には完全に同意しません。
文書化する必要があると私が思うのは、あなたのインターフェースです。つまり、クラスとメソッドの上にコメントが必要です。もちろん、set や get のような単純なメソッドではありません。
あなたが作成したクラスとメソッドを使用する人は、それらの使用方法を理解するためにあなたのコードを読む必要はありません。したがって、重要な不変条件と同様に、有効な入力と出力の範囲を文書化する必要があると思います。たとえば、関数はポインタを引数として取ります。関数にどんなに適切な名前を付けても、NULL の提供が有効かどうか、または NULL が有効な返される結果であるかどうかは明らかではありません。多くの場合、-1 と 0 は、検索されたオブジェクトが見つからない、または同様のものを示すために使用されます。それは文書化されるべきです。
それとは別に、コードを文書化する際の鍵は、クラスやメソッドが何をするか、または何であるかを文書化することではなく、その背後にある意図を文書化することだと思います。
あなたと同僚の間でコーディング規約を持ちましょう。インデントから始めて、「中かっこはどこから来ますか: 新しい行ですか、同じ行ですか?」 まで、かっこを覆います。
Visual Studio では、このスタイルを選択して修正できます。チーム内の他のすべての人が同じコードを読むのに役立ちます。また、「空の」編集 (スタイルの変更) と実際の編集を区別する必要がない場合、バージョン管理システムでの履歴追跡がはるかに簡単になります。
Eschewcodejunk。
エドワードタフテは、チャートジャンクのこの美しく強力な概念、情報ではなくノイズに寄与するチャートの視覚要素を持っています。このようにチャートを考えることで、より明確なチャートを作成できます。
同じような考え方をコードに適用すると、はるかにクリーンなコードが得られると思います。例としては、/* getFoo() gets the foo */スタイルのコメント、不要な括弧と中括弧、過度に具体的な変数名、ハンガリアン記法のいぼなどがあります。
チャートジャンクを構成するものは、チーム、環境、およびプロジェクトによって異なります。いぼのような人もいます。一部の環境では、特定のジャンクを有用な方法でコードをレンダリングします（// end forたとえば、中括弧のマッチングやコメントなど）。一部のプロジェクトでは、標準に準拠したり、APIを包括的に文書化するために、より広範なコメントが必要です。しかし、チームがプロジェクトにとってchartjunkが何を意味するかについての基準を確立すると、多くの決定が容易になり、そのコードはより一貫性があり、読みやすくなります。
コーディングしている環境内で使用されているパラダイムに固執します。
明らかな例は、.NET ではメソッドに Pascal ケースを使用し、Java ではキャメル ケースを使用することです。
あまり明白でない例は、標準クラス ライブラリで使用されているものと同じ規則の使用に関連しています。
この目標については、言いたいことがたくさんあります。命名規則は人間には多くの情報を伝えますが、コンパイラーにはほとんど情報を伝えません。ある環境で別の環境の規則を使用する API を使用したことがある人なら誰でも、異質なコードがどれだけ際立っているかに気付いています。
一貫性は、人間のコード消費者の認知負荷を軽減する貴重な特性です。
すべての回答 (および質問) は、読みやすさはコード ライターの責任であるという前提に基づいています。本当にコードを読みたくないのに、利用可能なコードの 99% に一致する今すぐ読むのをあきらめたリスト (コードのにおいがする) があり、コードが何をしているのかについて真剣に考えたくない場合は、その場合、読み取り可能なコードは見つかりません。
コードを読みやすくするために現在使用しているルールが何であれ、10 年後には時代遅れで馬鹿げたものに見えるでしょう。コードの可読性を本当に高めたい場合は、古いコードを読んで (当時の流行を考慮して、速度とメモリが 1000 分の 1 のマシンで実行する必要がありました)、それを理解する努力をして、他の人を励ましてください。同じことをする。