Clever Geek Handbook

良いコードコメントの書き方：「方法」ではなく「理由」

こんにちは、Habr！ジャック・フランクリンによる記事「良いコメントを書く：理由ではなく、方法」の翻訳をあなたの注意を引くために提示します。



画像



プログラミング環境でコードをコメントアウトすることは、多くの場合、時間の無駄またはコードを改善できるというシグナルと見なされます。これは私がGitHubで見つけたCONTRIBUTING.mdファイルからの引用です（そしてそのような例はたくさんあります）：

コメントは避けてください。コメントなしでコードを理解できない場合は、それ自体を説明するように書き直してください。


ほとんどの場合、そのようなアドバイスは失敗し、間違っていると思います。 このアプローチは、プログラミングを学んだほとんどの人の学習体験にそのルーツがあると思います。私が大学でコンピューターサイエンスを学んだとき（このアドバイスは多くのコースで見られますが、必ずしも大学のコースである必要はありません）、最初の学期に次のように言った1人の教師をよく覚えています。

コードの各行には、その機能を説明するコメントが必要です。コースでのあなたの仕事は、この基準に照らして判断されます。


それで、あなたがこのコースを始めたばかりの焼きたての学生であるとしましょう。何をする？もちろん、コードにコメントしてください！ 



//      bar
const inputValue = process.ENV.bar

//     2
const newValue = inputValue * 2

//     square
const finalValue = square(newValue)

//         
const square = (x) => x * x


コメントが悪いと言う人は、実際にこのようなコメントを考えています。そして、彼らは絶対に正しいです！プログラミングで「どうやって？」という質問に答える上記のようなコメントは、まったく役に立たない。これらのコメントはすべて、コード自体から理解できないものをコードに追加しませんでした。



「なぜ？」という質問に答えてください。



上記のコメントの問題は、それらがどのように説明するかということです。コードで実行する手順について説明します。このようなコメントが役立つことはめったにありません。コード自体は、何をすべきかを伝えるのにはるかに優れています。結局のところ、コード行は、タスクを完了する方法をコンピューターに指示する単なる指示です。



通常、コメントが豊富である必要はありません。理解できない外観を与える機能やニュアンスのない単純なコードを記述できるからです。しかし、基本的で直感的なコードを書くことが不可能な場合があります。多分それはあなたが回避しなければならないバグです。または、過去の開発者から、希望する方法で問題を解決できないシステムの形で幸せを継承しました。または、結局のところ、コードを改善する簡単な方法はありません。



かつて加工会社で働いていました。毎日、支払うべき支払いを選択する巨大なSQLクエリを実行しました。クエリは十分に最適化されており（非常に高速である必要がありました）、非常に複雑で、多くのエッジケースを考慮する必要がありました。できるだけ明確にするために一生懸命努力しました。ただし、このリクエストは完全に直感的で理解しやすいものではありません。それは、私たちの会社の文脈とそれがどのように機能するかでしか理解できない条件とロジックの束を含むコードが多すぎました。



ここに示す例を見つけたかったので、Reactコードベースの荒野に行って何かを見つけました。それを理解するためにReact開発者である必要はありません。だから、ここに私が強調したいコードがあります： 



//  key     .    , 
//  key      (, <div {...props} key="Hi" />
//  <div key="Hi" {...props} /> ).     key,   ,
//      jsxDEV   , 
// <div {...props} key="Hi" />,       ,
//    key   . 
if (maybeKey !== undefined) {
  key = '' + maybeKey
}


（そしてここにGitHub上のそれへのリンクがあります）。



コード自体に注意してください。 



if (maybeKey !== undefined) {
  key = '' + maybeKey
}


それが何をするのか理解するのはそれほど難しいことではありません。 mayKeyが指定されていない場合は、文字列化されたmaybeKey値をkeyに割り当てます。注：これは、'' + maybeKeymaybeKeyの内容を文字列に変換するためのJavaScriptのちょっとしたトリックです。



しかし、ここでの全体的な質問は、理由についてです。このコードへのコメントは素晴らしいです。彼は問題を指摘し、2つの例を挙げ、この問題を長期的に解決する方法と私たちが短期的に行っていることについても説明します。



私が書いたコードに残したコメントを見たい場合は、そのうちの1つ（TypeScript / ClosureCompiler）をご覧ください。これは、私が非常に価値があると思うタイプのコメントの良い例です。



結局、どんなコードでも理解することができます。結局のところ、コードはコンピュータに進め方を指示する指示にすぎません。コードは混乱する可能性がありますが、嘘をつくことはできません。時間が十分であれば、開発者はコードを段階的に実行して、コードが何をしているのかを理解できます。彼がなぜそれをするのかを理解するのは時々はるかに難しいです。ですから、あなたの同僚（または今から6か月後の未来）に、あなたのコードが何をするのか、そして何のためにそれが何をするのかについての文脈を残してください。それははるかに良くなるでしょう。


More articles:


All Articles