「すべてを正しい方法でコメントする」と「コメントを書く代わりに、より読みやすいコードを書く」。 -両方の有効な戦略？
適切なコメントの実践について学ぼうとしたところ、矛盾する意見がたくさん見つかりましたが、それは明らかに非常に主観的なトピックです。それで、「コメントすべきか、コメントすべきでないか」と尋ねることはしません。
私が提起したい質問は、私にとって、将来的にプログラミングの仕事に応募することに興味を持っている独学の開発者として、重要なものです：2つの戦略のうち
「rightコードをrightコードでコメントしてください。」 -（必要に応じてコメント）
そして
「コメントを書く代わりに、もっと読みやすいコードを書いてください。」 -（コメントが必要な場合は、コードに問題があります）
どちらもプログラミングで有効な戦略ですか？
見事に書かれたコードを含み、コメントがないコードサンプルを含むアプリケーションを提出すると、経験豊富なプログラマはそのアプローチに精通している可能性がありますか？
私は「特定の人が私のコーディングスタイルのように私のアプリケーションを読んでくれるのか」と尋ねているのではなく、明らかに誰もそれを推測することはできません。全体としてひどい。
あなたの質問は、存在しない二分法を意味します。
よりクリーンなコードを作成する必要があります。そうすることで、ドキュメント化する必要がない場所で十分に明確になりますか？ 絶対に。
コードの明確さと理解を向上させるのに、コメントを書いたり、その他の方法でドキュメントを提供したりする必要がありますか？ もちろんです
なぜこれら2つは相互に排他的ではないのですか？
- 記述したコードの中には、読みやすさよりもパフォーマンスの向上を優先するものがあります。
- アーキテクチャは自己文書化されていません。分離されたコードは、それがきれいに書かれていれば一般にかなり理解しやすいですが、それを取り巻くアーキテクチャは必ずしもそうではありません。
- 設計上の決定は必ずしも自明ではありません。
- コードがどのビジネスプロセスまたは問題を解決するかは必ずしも自明ではありません。
つまり、常に完全に自己記述的な方法で重要なコードを作成することはできません。あなたの仕事の一部は、あなたの後に来る仲間があなたのコードを理解するのに1年を必要としないことを保証することです、そしてそのためには、良いドキュメントが必要です。
時には、いくつかの追加の説明を必要とする可読コードを書くことができます。通常、これらはwhyの質問に回答するか、セキュリティまたは明白ではない可能性があるその他のタイプの問題に対して警告します。たとえば、先週コメントを書きましたが、 subprocess.check_call への呼び出しの前に glob.glob への呼び出しはShell=Trueの指定を回避するためであることを説明しました。セキュリティリスクです。
それがなければ、将来のメンテナーは私がそれを不必要に複雑にしたと思うかもしれません。彼らはそれをリファクタリングし、check_callは失敗します。彼らはドキュメントに行って、Shell=Trueが必要であることを確認し、うまくいけばそこに大きな赤い警告が表示されます。したがって、せいぜい、私のコメントは将来のメンテナをしばらくの間救ってくれました。最悪の場合、それは偶発的なセキュリティホールを救いました。
しかし、それは私が書いた最後のコメントを思い出すことができる何かを言っていることに注意してください。これらの状況は特に頻繁ではありません。
これを実行する http://www.doxygen.nl/index.html が役立つ場合があります。
ドキュメントは必要ですが、すべての変数、ループ、コード部分についてコメントする必要はありません。宣言時に関数が何をするか、許容できる入力、o/pの予想されるタイプなどを説明し、ファイルの全体的な機能を説明し、シミュレーションしている実世界のエンティティなどを説明すると役立ちます。これは、将来のプログラマーが保守可能なコードを書くのに役立ちます。
ただし、関数、ファイル、変数などの名前は、わかりやすいものにする必要があります。余波を経験したことがない人は、実行できないステートメントを無視する傾向があるため、これはプログラムの読者に役立ちます。また、読者は急いでいる場合、通常は余分なものを読みたくありません。基本的な例-異なる方法で処理する必要がある変数の複数の可能な値の場合、switch-caseステートメントを使用すると、if-elseif-elseのチェーンを使用するよりも説明がわかりやすくなります。後者の場合、コメントを付ける必要があるかもしれません。前者の場合、コードはその背後にあるアイデアを記述しています。
名前とコーディングスタイルがコードを適切に説明しておらず、別のコーディングスタイルを使用するとパフォーマンスに影響する可能性がある場所では、コメントを使用できます。