あなたのコードをコメントしてください

私はこう言うためだけに立ち上がります:

あなたのコードをコメントしてください。

プログラマーに会うたびに (時にはかなり上級のプログラマーもいますが)、彼は次のように考えていることに気づきます。コードにコメントを付ける必要はありません。言っておきますが、これはでたらめです。私は長い間これを言い続けてきました。問題は、物事を変えるのは思っているよりも難しいということです。私たちは、厄介なコードを一生懸命書き、素晴らしい新しいものをリリースする準備をしている岐路に立っているにもかかわらず、ほとんどすべてをコメントアウトしています。これらのことをやらない理由はありません。コードの 3 ～ 7 行ごとに、長い記事が公開されます。場合によっては、数百行のコード内に良いジョークが見つかることがあります。

隠れ場所が間違っています

ほら、1つはあなたが望むものであり、もう1つはあなたが達成するものです。あなたのバグはその中間にあります。コメントを書くということは、あなたが何を望んでいるのかを私に伝えることになります。コードでそれをどのように行うかを教えてください。プログラムの欠陥は、あなたが望むアイデアにあるか、要件は正しいがコードに何か問題があるかのどちらかです。助けて、どれが間違っているか教えてください。

怠けないでください

よくある反対意見は次のとおりです。コードは頻繁に更新されるのにコメントは更新されないため、コメントの有効期限が切れることが多いと聞きました。コメント更新してないの？あなたの同僚もそうですか？怠け者になってはいけないし、怠けていても大丈夫だと人々が考える文化を作ってはいけません。あなたがプログラムにどれほど細心の注意を払って注釈を付けているかを同僚に伝え、彼らにも同じことを期待していることを伝えてください。コメントしないというのは、将来誰かまたはどこかがあなたに間違いを引き起こすのではないかと心配しているからです。これはただの言い訳です。

あなたは経験豊富です

人は無知で当然ですが、あなたは経験豊富です。したがって、学ぶ必要がある人を教育する義務があります。あなたのコメントは、コードを読んでいる人のガイドになります。ここで他のものではなくタプル データ構造が使用されている理由を説明してください (さらに良いのは、スタック オーバーフローまたは dotnetperls へのリンクを添付することです...それは完全に可能ですよね?) ここで何をしているのですか?ショートカットを使用しないと時間通りにリリースすることはできないため、これらの初心者に遭遇した特別な状況について伝えてください。そうしないと、最終的には悪いコードがコピーされ、あらゆる場所に拡散されてしまいます。見て！あなたが書いた悪いコードは、会社のプログラムのテンプレートになります。まったくコメントがありません！

と入力できます

私の採用プロセスは、一部はホワイトボード プログラミング、一部はキーボード プログラミングでした。優れたプログラマーは皆、優れたタイピストです。 1 分あたり 40 ～ 60 単語を入力できるとします。だったら教えてください、コードをマシンガンのように書くときにコメントを追加したらどうですか？もちろん、コードがこれほど混乱している理由は、ビジネス担当者が 75,000 ドルという莫大な費用と引き換えにプログラムを今週リリースする必要があるからである、と 30 秒もあれば教えていただけます。しかし、来月はどうでしょうか？これらのコードはもう必要ありませんか?石に封印されてる？このコードが何をしているのかはわかっています。しかし、あなたの意図を教えてください。

あなたは日に日に年をとっていきます

聞いてください、私は長い間、おそらくあなたが中学生になる前からプログラミングをしてきました。私は今でもプログラミングをしていますし、プログラミングが大好きです。いつかあなたも私と同じ年齢になるでしょう。あなたが私と同じなら (その当時、私にはもうあなたを教育する能力はありません)、その時点では、層が多すぎ、抽象化が多すぎ、技術的なアーキテクチャが多すぎて完全には覚えられません。あなたのコメントはあなたを導くために出てきます。彼らは、6 か月前にこの方法とこのモデルを使ってそれを達成した、そして誇示するためだけにやったと言うでしょう。あなたが本当に優れたプログラマーであり、今でもプログラミングを行っている場合は、このコードの書き方が悪く、別の方法で再実装する必要があることに気づくでしょう。そして、何を考えていたのか、なぜそれを行ったのかを思い出すためのメモがまだ残っています。

それでは、あなたのコードをコメントしてください。

[この記事の英語のオリジナルリンク: あなたのいまいましいコードをコメントしてください]