私は若いプログラマーです(コンピューターサイエンスの大学は終了していますが、業界で1年未満働いています)。最近、まともなサイズのWebサービス用のCコードの作業に就きました。コードを見ると、コメントを見た唯一の場所は、人々が古いコードを隠していたときでした。ほとんどの場合、関数名と変数名も同様に情報を提供します-futex_up(&ws->g->conv_lock[conv->id%SPIN]);
。状況について上級プログラマと向き合い、コメントと意味のある名前を追加することで、将来的にコードの保守性と可読性が向上することを説明すると、次の返答が返ってきました。
一般的に、私はコメントが嫌いです。ほとんどの場合、戻り値で言及した場合のように、人々はコメントを使用してコードを読み回します。コメントは、その人がコメントを入力したときにコードが何をしたと思ったのか(それは多くの場合、最後の編集の前にあります)以外は何も言いません。コメントを入れると、人々はコードをあまり読みません。そうすれば、バグが捕らえられず、人々はシステムの癖やボトルネックなどを理解しません。コメントが実際にコードの変更で実際に更新されている場合、それはもちろん完全に保証されていません。
私は人々にコードを読ませるよう強制したいと思います。同様の理由でデバッガーが嫌いです。それらは非常に便利であり、コードが十分に単純化されていないためにコードにバグがあることが本当の問題であった場合、ウォッチとブレークポイントでダーティコードをステップ実行し、いわゆる問題を見つけることができます。デバッガーがない場合は、醜いコードの読み取りを拒否し、何が行われているかを確認できるようにこれをクリーンアップする必要があると言います。クリーンアップが完了するまでに、バグの半分の時間がなくなります。
彼が書いたことは私が大学で教えられてきた多くのことに対して反対ですが、それはいくらか理にかなっています。しかし、研究の経験は実際の生活ではうまくいかない場合があるので、私はより多くのコードで精査された人々の意見を得たいと思います。
ユーザーが実際にコードを読んで、中規模のコーディング環境で何が起こっているのかを理解するためにコードにコメントを付けることを避けるアプローチです(1〜2か月以内に作業するすべての人が全体的に合理的に読むことができるもの) 、またはそれは長期的な災害のレシピですか?このアプローチの長所と短所は何ですか?
よく書かれたコードは十分に自己文書化されている必要がありますwhatコードを説明するコメントは必要ありません。コード自体を読むことから明らかであるためです。これは、すべての関数と変数が説明的な名前を持っていることも意味しますが、問題と解決策のドメインの専門用語を学ぶ必要があるかもしれません。
重要なコメントはwhyを説明するコメントであるため、適切に記述されたコードは完全にコメントなしであるべきだという意味ではありません。別のソリューションが選択されました。
コード自体を説明するコメントの問題は、バグを修正するためにコードが変更されるため、コメントが古くなる傾向があることですが、コメントはそのまま残ります。これは、現在の解決策にたどり着く理由を説明するコメントでは、はるかに少ないケースです。
誰かが( Richard C. Havenに帰属 、Delphiプログラマー)かつて書いた:
初心者は何もコメントしません。
船員は明白にコメントします。
_myVar = myVar + 1; // add one to myVar
/* This method adjusts the page margin by the appropriate device offset */
_
マスターは別の方法でそれをしない理由をコメントする
_/*
I already tried obvious approaches A, B, and C to solve this problem.
They didn't work for the following reasons: ...
Therefore I wrote this less-than-obvious approach which works and
passes all unit tests.
*/
_
あなたの「シニアプログラマー」は、年齢/寿命の点でシニアの可能性がありますが、彼には専門家が育っているように思えます。
デバッグに関しては、クリーンなコードと、ロギングおよび/またはprint()
ステートメントの自由な使用については多くのことが言われています。ただし、優れたデバッガーを使用すると、通常、問題がなければ、ほんのわずかな時間で問題を見つけることができます。それは動力工具です。これを使って。
私は人々にコードを読ませるよう強制したいと思います。同様の理由でデバッガーが嫌いです。それらは非常に便利であり、コードが十分に単純化されていないためにコードにバグがあることが本当の問題であった場合、ウォッチとブレークポイントでダーティコードをステップ実行し、いわゆる問題を見つけることができます。
あなたの上級プログラマーはコーディングスタイルについて理解できる問題を抱えているようです。しかし、彼は問題への取り組み方が間違っています。
両方コメントと説明的なコーディングは不可欠です。説明的な名前の付いた適切に記述されたコードは、どのコードが行うか;しかし、コメントはコードが何をすべきか(そしてなぜそうでないのかを教えてくれますanother。次に、「契約」(コードすべきこと)が実際に満たされていることを確認するユニットテストがあり、自動的に、頻繁に、これ以上の努力は必要ありません。
コメントがないと、時間がかかります(または、単体テスト。この時点では、上司が「コードを読んでいる人にバグが捕まる)」と信じている場合、コメントよりも嫌いだと思います。エラーを見つける前に:
// Multiply margin by a fixed amount.
page->margin += fixedMargin;
そして、はい、コメントは間違っている可能性がありますが、これで2行のうちの1行にエラーがありますであることがわかりました。これに加えて、別の有用なリソースversion controlを使用すると、30秒未満で矛盾を見つけることができます。出力を確認し、デバッガーを使用してステップ実行することもできない場合があります(たとえば、fixedMarginの値が約1.01の場合、結果が不明確になる可能性があります)。
あなたのメンターが単純さを求めている場合(私はそれが望ましい特性であることに同意します)、彼は 循環的複雑度 などのメトリックをチェックし、メトリックの目標を確立する何らかの方法を展開する必要があります。それはコメントにも当てはまります。コードのすべての1行を文書化することは意味がないことに同意しますが、モジュール、関数、およびコード内の「WTFポイント」をカバーするよう努めるべきです。
// Useless comment: multiply a by four
// Useful comment (even if maybe it shouldn't be in this exact point of code):
// Zooming 2:1, four pixels get mapped into one, divisor needs multiplying by four
a *= 4;
彼の方法は結果をもたらすかもしれません-彼が嫌いな場合、あなたは20%のコーディングと80%の文書化とテストをするでしょう。彼の方法を使用すると、20%のコーディングと80%のデバッグとスクラッチが得られます。
2つのケースの違いは、人々の士気と全体的な生産性の違いだと思います。関数とモジュールを適切に文書化してモックする場合、モジュールは誰かが実装できます全体像を知る必要がない人、ブラックボックスシナリオでの副作用を研究する必要はありません。一番下の行のために、経験を少なくすることができます。
あなたのメンターは恐ろしいほどの量の 技術的負債 を実行することに明らかに快適です。締め切りの遅れやETAについて彼の統計を確認します。奇跡がなければ、ワンマンバンドや緊密に結びついたコーディングバディのグループによって追いつけられていない長期的なプロジェクトは、遅かれ早かれその技術的負債が問われることになります。
「コードを読み取る」ことしかできない場合、関数が何であるかがわかりません意図された。したがって、誰かが干渉し(私は誰も知らない、これは架空のケースです)、何か間違ったことをした場合、コードでそれをチェックする方法はありません。ユニットテストがそれを検出するのを待つ必要があります(チェックする場合)。
それに加えて、コメントを追加しないと、関数A1、A2、A3 ...を最初から最後まで読む必要がありますが、私は上記のすべてを呼び出す関数Aのみを理解することに興味があります。
私はあなたの上級プログラマーが怠惰である(悪い)か、彼がいかに巧妙にコーディングしているか(もっと悪いことに)人々に気づかせたいと思います。
コメントを入れると、人々はコードをあまり読みません。そうすれば、バグが捕らえられず、人々はシステムの癖やボトルネックなどを理解しません。コメントが実際にコードの変更で実際に更新されている場合、それはもちろん完全に保証されていません。
意地悪な馬鹿みたいなものはない。
次回、本を読んで買い物をするとき。購入する前に必ずお読みください。そうでなければ、それがあなたが購入しようとしていたものであるかどうかを正確に知ることは決してないでしょう。それは基本的に彼があなたにやるように言っていることです。
彼は愚かであるいくつかの仮定をしました。
scope
に関連しています。それはコメントについての彼の狭い見方であり、そのため彼はコメントに価値を見いだしていません。コメントがないことの制限は次のとおりです。
open window, Prompt for deposit
は、プログラマがユーザーに警告を伝えることを意図していたことを説明していません。次回この男と会話したとき、彼はなぜソースコードにコメントを追加するのかと尋ねました。このステートメントで返信します。
「私はコンピューターに何をすべきかを伝えるためにソースコードを書き、何をすべきかを人々に伝えるためにコメントを書きます。」
コメントは、紛らわしいことを説明する記録として使用する必要があります。混乱を招く可能性があり、単純化できないものを書いている場合、6か月後に理解するのが難しいと思う場合は、コメントを書き込んでください。
あなたが自由にコメントすると、すべて、どこでも、コメントは困難を報告する効果を失います。 (「オオカミ!」と泣いた少年の寓話を思い出してください)
優れた折りたたみエディタがない限り、コメントは「画面領域」を占めます。コード内を移動するときは、それらをスキップし続ける必要があります。そしてもちろん、/* increment i by one */
の横にあるi++
のようなコメントは完全なゴミです。
コードが非常に複雑で内部へのガイドが必要な場合は、うれしいことに内部へのガイドを記述します。それをREADME-internals.txt
(またはおそらくHTML)と呼び、コードと同じディレクトリに隠し、/* this is all explained in README-internals.txt */
と言うコメントを付けます。
デバッガーについて:バグを見つけるのに役立つツールはどれも貴重です。ツールを却下するのはばかげています。コードが機能していることを確認するために、ブレークポイントデバッガーを使用しないでください。少なくとも、主要な手段として信頼されていません。デバッガーはCのa[i] = i++
のようなステートメントを陽気にステップオーバーし、悪い直感を確認します。
ただし、ある種の実行時違反を実際にキャッチするデバッグツールは、テストツールとして信頼できます。動的メモリの誤用を検出するデバッガーがあり、コードがそのデバッガーの下で多数のテストケースに合格する場合、それはメモリが誤用されていないという信頼の源です。
したがって、「デバッガ」は、ブレークポイント/ステップデバッガだけでなく、複数の種類のツールを指すことに注意してください。一部のデバッガーはプログラムのビューのみを提供し、何が問題かについての推論をあなたに任せますが、他のデバッガーは問題を探します。
デバッガーがないか、デバッガーの使用を拒否するために、コードを常に簡略化できるとは限りません。上司の提案に従い、コードをこれ以上単純化できなくなるほど単純化しても、デバッガが必要な場合はどうでしょうか。
コードレビューは、この質問に具体的に答えるための素晴らしいプロセスだと思います。私が誰かのプルリクエストを読んで(すべてをすぐに明らかにする必要があるという態度でそれをちらっと見るだけでなく、実際に読む努力をして)、それが何をするのか理解できない場合は、コメントを追加するように伝えます。または、ゴム製のアヒルを使って自分でこれを行うこともできます。
ほとんどの人は直感的にコメントする必要があるアイデアを知っています-コードについて質問した場合、あなたの隣に立っている誰かに言うことは何でもです。しばしば私は誰かにレビューで何かを説明するように頼みます、彼らは素晴らしい答えを与えるでしょう、そして私の返事は「あなたがコードでコメントに書いたその説明をコピーしてください」です。
しかし、何らかの理由で、それが人々がコメントで最終的に書く内容になることはめったにありません。代わりに人々は次のような狂ったものを書く
/**
* Gets the {@link List} of {@link Author}s for the given {@link Book}.
*
* @param book The {@link Book} for which you want the {@link Author}s.
* @return All of the {@link Author}s for the given {@link Book}.
*/
List<Author> getAuthors(Book book) { ...
そして
// increment i by 1
i += 1
経験豊富な同僚が反応しているようなものです。私がコードを見直して、すぐ近くにある行で見つけることができるよりも多くの情報を追加しないこれらの種類の低レベルのコメントを削除するとき、私自身も人々に話します。
doesにコメントする必要のある些細なことの1つの主要な例は、動的言語のアヒル型の説明です。関数の引数または戻り値が一連のプロパティを持つdictである場合、それらのプロパティについて正確にコメントしないと、後で少し狂気になることがあります。
8歳の子供が理解できるレベルまで重要なコードが増えることはないので、試してはいけません。読者はコードの読み方を知っているというsomeの仮定を行う必要があります。それ以外の場合は、まったく無駄な作業になるためです。
最後に、コメントが間違っていることがよくあります。人々は読むときにそれらをスキップすることが多く、状況が変化しても更新しません。コメントの単体テストを作成することはできません。そのため、不注意な同僚が不満を抱き始めたときに発生する腐敗からコードを守る唯一の方法は、アイデアのみをコメントすることです。値を追加しないコメントは、エラーになると負の値を追加します。
ドキュメントのデザイン、アイデア、アーキテクチャ、歴史、理論的根拠-コード行ではありません。
期限のない完璧な世界では、彼のアプローチはうまくいくかもしれません。
ユーザーがアプリケーションXのバグを報告しました。新しい担当者が2か月かけてコードを深く完全に理解し、数週間のリファクタリングを追加できるようにします。それでもバグが発生する場合は、そのバグを見つけることができ、デバッガーも必要ありません。
現実の世界では、これはビジネスから抜け出すための信頼できる方法のように聞こえます。
悪いコメントの例
foo(); //calling function foo
良いコメント
foo(); // must call function foo, because of a bug {link to bug}
Code Complete、コーディングスタイルに関する重要な作業は、いくつかのセクション(エディション1の19.3以降)をコメントの質問に当てています:善、悪、そして醜い。したがって、あなたとあなたの上級開発者はおそらくそこを見る必要があります。
とはいえ、大規模なプロジェクトや長期的なプロジェクトでは、適切に記述され配置されたコメントが非常に重要なIMOです。
完璧な世界では、コメントは重要ではないのは事実です。しかし、写真の記憶がなく、コードに取り組むすべての人が天才でない限り、良いコメントは、1、2年後に戻ってコードを変更する必要がある場合、または他の誰かが継承する場合に、コードをはるかに迅速に理解するのに役立ちますあなたのコード。 (私はこれが20年間専門的に働いていたと言っています、そして他のいくつかの開発者が関与する1つのプロジェクトで5または7年もの多くも)
数年前、私はその仕事を成し遂げるが、貧弱なアーキテクチャと一貫性のない肥大したコーディングスタイルに悩まされている複雑なアプリケーションを継承しました。幸いなことに、コードはかなりよくコメントされているので、そのコードベースに慣れるために何日も何週間も節約できました。
速度を上げるのに役立つもう1つのことは、使用するデバッガーです。自分が取り組む必要のある新しいソフトウェアを分析するとき、最初に行うことの1つは、すべてのメニューを調べ、無効または奇妙な選択を行い、アプリを壊すことができるかどうかを確認することです。私はそれを壊すとき、私はデバッガーでそのシナリオを実行し、その失敗が私をどこに導くかを確認します。ほとんど常に、これはコードベースの重要なモジュールとジャンクチャに私を導きます:マップ上の重要な場所を見つける簡単な方法。
私自身のコードでは、通常、デバッガーをあまり使用する必要はありませんが、それが役立つ場合があります-ユニットテストに細心の注意を払っていても、誰も完璧ではありません(密結合を継承した場合は、多くの場合不可能です)レガシーコード。)そして、新しいモジュールまたはコンポーネントを使用する場合、デバッガーは、新しいものに慣れるために対処しなければならないエラーや誤解をすばやく見つけるのに役立ちます。
要するに、時は金なり、そして私たちのほとんどは製品を配達して請求書を支払うようにプログラムしています。デバッガーが10秒で明らかにするバグを見つけるために何百行ものコードを調べて何週間も座っているか、または適切なコメントで照らされている可能性のある不適切に記述されたコードは、最終的な収益にあまり役立ちません...
あなたの上級開発者は明らかに効率に関心がなく、いくつかのコメントで1日を節約できる場合、開発者に複雑なコードをいじるのに何時間も何日も費やすことを好みます。デバッグについての彼の考えにも同じことが言えます。 (ちょうど気になるところ:上級開発者はIDEを使用していますか?テキストファイルにすべてを入力して、コマンドラインなどからコンパイルとリンクを行うだけではどうですか。コードのすべての1行を理解するためのより良い方法...)
コメントは、男がコメントを入力したときにコードが何をしたと思ったのか以外は何も言いません
ご存知のように、これは非常に理論的なアプローチです。理論的な数学者が言っていたとしても、私は驚かないでしょうが、上級開発者の音では、それは本当に長い練習をしている人のようには聞こえません。
理論的には、コードを頭で分析できますが、非常に単純なプログラムでのみ機能します。より複雑で現実の問題に出くわすと、計算理論で最も複雑な問題の1つである Halting problem になります。誰かが頭の中でプログラムを分析できると言ったら、おそらく彼はメモリでRSA復号化を行うことができます:)
上級開発者が複雑な問題の実際の経験がないか、ハッカー映画から取られたトリックを使って印象づけようとしている、または彼はコメントを書くとき、自分のlazinessを正当化したいと考えています。
私は約40年前からコードを書いており、その上級プログラマーの言ったことと非常によく似たことを言ったかもしれません。メンテナンスの問題もよく知っています。
それでも、上記の回答ではいくつかの非常に重要なポイントが忘れられていたと思います:
ほとんどのコードでユニットテストを使用しています。ね?
関数の理由(コードの背後にある意図)は通常テストを通じて表現され、テストだけでは十分ではない場合はコメントが付けられます(場合によってはがらみのプログラミングを聞いた場合) 彼らは私が話していることを理解しているかもしれません)。
私のコードの反対のコメントは、2つの特別な場合を除いて、非常にまばらで、ほとんど存在しません。-実装されているものがいくつかの規範的な参照(ネットワークプロトコルの実装など、現在取り組んでいるもの)に従っている場合、通常は参照を配置します。コードの上にコメントとして。 -プログラミングフローを壊さないようにコメントも使用しています。私は次のようなコメントを挿入します:これまたは間違って見える、後で修正する無関係な機能をコーディングするとき。これらは(プログラマが定義した警告のような)短期間のコメントであり、後で修正する必要があります。
そうすることについての私の理論的根拠は、コード内のコメントは誤解を招く可能性があるということです。あなたはコメントを簡単に読むことができ、たとえそれが真実ではない場合でも、コードがコメントのふりをしていることをコードが信じている。
コードに関するコメントがテストにある場合、状況は異なります。コードの呼び出し方法とについて説明し、テストが実際にそれを実行していることを確認します。
私は通常、デバッガーをあまり使用しません。いくつかの特別な場合(主に、奇妙なハードウェアバグなど、コードの機能がわからない場合)に備えて保管します。
それは時間とともに変化しました。 30年前、私はデバッガを多用しました。私が観察したことは、バグを見つけることは通常他の方法よりずっと遅いということです。私が今やっていることは、単体テストのバグを特定することです。これには、非回帰テストを提供するという追加の利点があります。同じバグで二度噛まれることはありません。
コメントはwho、when、why、assumptions、dependanciesの可能性があります。 方法。
誰がこれを書いたのですか?質問がある場合、誰に行ってバグを報告しますか?
彼らはいつそれを書きましたか?
なぜ彼らはそれを書いたのですか?コードの作成に時間を費やしたビジネス上の理由は何ですか?
なぜ彼らはこのアプローチを選んだのか、そして他にどのようなアプローチを拒否しましたか、そしてなぜですか?
彼らはどのような仮定をしましたか?彼らは組織についてどのような信念を持っていましたか?
このコードを正常に実行するには、何が必要ですか?どのライブラリ、オブジェクト、環境、その他に依存していますか?
コードが失敗する可能性がある状況と、コードはそれらの失敗をどのように処理するのですか?それらにどのように対処しますか?
「方法」に関しては、コメントがコードがどのように機能するかを説明するのは、コードが複雑で理解しにくい場合のみです(そして、コードが複雑な場合は、おそらくプログラマーはコードの簡略化にもっと力を入れたはずです)。
上級開発者が言及しているのはコードエントロピーです。私は彼がコードの設計が不適切であるケースに言及していると思います。そしてそれをよく理解してそれを扱う唯一の方法はコメントとデバッガーです。
つまり、コメントとデバッガーを使用して、根本的な問題を回避できます。ただし、これらは両方ともツールであり、ツールを非難することは何でもする効果的な方法ではありません。
あなたの例では、コードベースに多くの壊れたコードがある場合、解決策はコメントを省略せず、誰もができるだけ多くのコードを読むようにすることです。実際、これは時間とリソースの浪費です。代わりに、ピアレビューやペアプログラミングなどのプロセスをセットアップします。この場合、ある人が書いたコードは別の人がレビューしたはずです。これらのプロセスは、より正確に同じ目標を達成するだけでなく、コメントやドキュメントがないために、何十人もの開発者が1つの複雑なコードを理解する必要があるリソースの浪費を回避します。
さらに、効率的なコメントは実際にコードのエラーの量を減らすことができます。それらを読み取ると、ソースコードが理解しやすくなり、多くの場合、コード行が必要な理由を見つけるためだけにソースファイルのバッチ全体を検索する必要がなくなります。確かに、コメントは間違っているかもしれません-しかし、プロジェクトの全体的な品質がまったくひどいものでない限り、古いコメントに負けてしまうよりも、正確なコメントを信頼することでより多くの時間を節約することになります。また、理解にかかる時間を節約することは、リファクタリングの時間を増やすことを意味します。これは、コードエントロピーと戦うためのより優れた方法です。
コードを書くときはいつでも、あなたが書いたものを継承する次のプログラマについて考える必要があります。ベストプラクティスとして、またはただの習慣としてそうするように教えられたためにコメントを書く場合は、コメントを書くのをやめるべきです。
命名規則と構造がコメントしているだけで、あなたがやっていることの奇妙な要素を説明できない場合(通常、コードベースの何かが完全にたわごとであることが原因です)、彼らはそれを理解します。コードの問題のある部分をマークしている場合は、大声で叫ぶために日付を記入して、ソース管理での不快感の原因となった変更を簡単に確認できるようにします。
デバッガーに関して言えば、私が推測しているのは、(おそらく)昔ながらの、主に手続き型の連帯感の連帯感を感じることができます。なぜなら、私はすべてのIEが「Object not見つかりました。」なぜ彼らが気になったのかはわかりませんが、そのようなことを時々処理する必要がある場合、何かが起こった場所がより明白になるような方法でコードを構造化する方法について、あなたはもっとずっと考えると思います間違っているため、ロギング/アラートで迅速に診断できます。
とは言っても、私はChrome DevツールやFirebugを時限旅行の交番以外のものと交換することはしません。でもポイントはこれだと思います。最初に行うことは、関係するコードを見ることさえせずにデバッガーでトレースを開始することである場合、コードを適切に構造化していない可能性があります。 IDEやデバッガを使用していないかのように、常に直接的で明白かつ最小限で読みやすいものになるように常に努めてください。最初に障害にぶつかったときにコードを確認することから始めます。問題が発生している場所を推測するのが容易ではない場合は、最新のツールを使用せずにコードを作成する方法をさらに検討する必要があります。私が今まで見たJavaとC#のほとんどは、OOPの基本的な基礎について無知です。
以前はコメントが多かったのですが、現在はほとんどありません。コードと変数の名前を読みやすくするのがよいでしょう。
私は本当の「おかしなこと」と「なぜこれが行われたのか(コードからは(まだ)明らかではない)」というコメントを追加します。
しかし、あなたの本当の質問には。
私はあなたのタイトルが単語で始まることに注意してください: "強制"
また、最初の段落で「対決」について言及していることにも注意してください。
私は20年前に自分とまったく同じ言葉を使いました:)
これ(もちろん私見)は、プログラミングの本当の意味です-異なるスタイル、意見、経験、知識、および背景を持つ異なる人々がどのように連携できるか。
単純な修正はなく、実行するプログラムによる手順のリストも、物事を正しく設定するための会話もありません。 20年の経験から学んだ次の点を考えてみてください。
コメントは非常に過大評価され、最も頻繁に誤用されます。私はあなたの現在の状況については知りませんが(コードの読みやすさのために引用符で囲まれた引用が見つからないため)、一般に、コード全体にコメントをスプレーしないでください(おそらく、高レベルのコメントを除いて、すでにドキュメンテーション0に近い。
Martin Fowlers Refactoring bookで説明されているコードの匂いの1つがコメント化である理由です(概要については、 http://www.industriallogic.com/wp-content/uploads/2005/09/smellstorefactoringsを参照してください)。 .pdf 、本は自由に入手できるわけではありません)。
ただし、意味のあるメソッド名と変数名でコメントを置き換える必要があります。w
とgs
は分類しないと思います。ただし、個人的には、コメントよりも適切なネーミングを重視します。
ところで、「クリーンなコード」と「コメント」または「コードの匂い」と「コメント」を検索すると、これに関する優れた読み物が見つかります。 http://franksworld.com/blog/archive/2010/07/01/12035.aspx (クリーンコードのボブマーティンおじさんがコメントを嫌う理由の概要)
コード内のコメントは、正しく使用すれば天の恵みですが、他の人が指摘しているように、頻繁に使用されすぎています。すでに指摘されていることを繰り返すつもりはありませんが、コメントを書くのは、作成しているコードが複雑であり、他に実行可能な方法がないことがわかっている場合に限ってください。
コメントする必要があると思われる場合は、まずコードについて考えて、自問してください。なぜあなたはそのコメントを書いているのですか?コメントを必要としないコードを書く別の方法はありますか?
コメントを書くためにコメントを書かないでください。最後の手段として、またはコードをさらに下で作業する必要がある人を助ける場所としてのみコメントしてください。変数が何をしているかを説明するコメントを書いていることに気づいたら、おそらくあなたは過剰にコメントしているでしょう。悪いプログラマはすべてにコメントし、優れたプログラマは必要なときだけコメントします。
デバッガーについては、デバッガーを起動せずにすべてのキャリアを終えたエンジニアと協力しています。どうして?デバッガーは他のツールと同じです。ほとんどの場合、ボールピーンハンマーで十分ですが、より洗練されたものが必要になる場合があります。
デバッガーには2つの目的があります。
それらは、新参者をスピードアップするのに非常に役立ち、バグを見つけるのが非常に難しいものを追跡するのにさらに役立ちますが、それらが唯一の方法ではなく、デバッガーが実際には助け以上の障害になる場合があります。
関数の概要については、すべての関数にdocblockが必要です。これは必須ですが、長くて手の込んだものにはなりません。要約は、各パラメータが明確に記述された1行の説明である必要があります。
/**
* A getter method for foo
*
* @param bool $bar If true, bar will be attached to foo
*
* @return foo
*/
原因がある場合にのみ、詳細なdocblockを使用してください。メソッドが複雑すぎる場合は、はい、説明を入れますが、可能であれば、それを避けてください。適切なコードはそれ自体を文書化する必要があります。
誰もが小説を読むことを楽しんでいますが、月曜日の朝9時に戦争と平和を読みたがる人は誰もいません。