コードにコメントを入れる:良い、悪い、そして醜い。

これを聞いたことがあるなら止めて…

「優れたコードは自己文書化です。」

生計を立てるためのコードを20年以上書いてきた中で、これは私が最もよく耳にした1つのフレーズです。

それは決まり文句です。

そして、多くの決まり文句のように、それはそれに真実の核を持っています。しかし、この真実は非常に乱用されているため、フレーズを発するほとんどの人はそれが実際に何を意味するのかわかりません。

それは本当ですか?はい

コードにコメントを付けてはいけないということですか?いいえ

この記事では、コードのコメントに関して、良い点、悪い点、醜い点について説明します。

手始めに、実際には2つの異なるタイプのコードコメントがあります。私はそれらをドキュメンテーションコメントおよび説明コメントと呼びます。

ドキュメントコメント

ドキュメントのコメントは、ソースコードを消費する可能性が高いが、それを読み通す可能性が低い人を対象としています。他の開発者が使用するライブラリまたはフレームワークを構築している場合は、何らかの形式のAPIドキュメントが必要です。

APIドキュメントがソースコードからさらに削除されるほど、時間の経過とともに古くなったり不正確になったりする可能性が高くなります。これを軽減するための優れた戦略は、ドキュメントをコードに直接埋め込み、ツールを使用してそれを抽出することです。

これは、Lodashと呼ばれる人気のあるJavaScriptライブラリからのドキュメントコメントの例です。

これらのコメントをオンラインドキュメントと比較すると、完全に一致していることがわかります。

ドキュメントのコメントを作成する場合は、それらが一貫した標準に準拠していること、および追加する可能性のあるインラインの説明コメントと簡単に区別できることを確認する必要があります。人気があり、十分にサポートされている標準とツールには、JavaScript用のJSDoc、dotNet用のDocFx、Java用のJavaDocなどがあります。

これらの種類のコメントの欠点は、コードの保守に積極的に関与している人にとっては、コードが非常に「ノイズが多く」、読みにくくなる可能性があることです。幸いなことに、ほとんどのコードエディタは「コード折り畳み」をサポートしているため、コメントを折りたたんでコードに集中できます。

明確化コメント

明確化コメントは、コードの保守、リファクタリング、または拡張が必要になる可能性のあるすべての人(将来の自分を含む)を対象としています。

多くの場合、説明コメントはコードの臭いです。コードが複雑すぎることがわかります。「優れたコードは自己文書化」であるため、説明コメントを削除し、代わりにコードを単純化するように努める必要があります。

これは、非常に面白いものの、悪い説明コメントの例です。

/* * Replaces with spaces * the braces in cases * where braces in places * cause stasis.**/ $str = str_replace(array("\{","\}")," ",$str);

少し紛らわしいステートメントを巧妙な韻で飾るよりも(両生類の直径で)、作者はコード自体を読みやすく理解しやすくする関数に時間を費やしたほうがはるかに良かったでしょう。たぶん、?removeCurlyBracesという名前の別の関数から呼び出された、という名前の関数sanitizeInput

誤解しないでください。特に、圧倒的な作業負荷を抱えているときは、少しのユーモアを注入することが魂に良い場合があります。しかし、悪いコードを補うために面白いコメントを書くと、実際には、後でコードをリファクタリングして修正する可能性が低くなります。

あなたは本当にその賢い小さな韻を読むことの喜びからすべての将来のコーダーを奪う責任がある人になりたいですか?ほとんどのコーダーは、コードの臭いを無視して、笑って先に進みます。

冗長なコメントに出くわすこともあります。コードがすでに単純で明白な場合は、コメントを追加する必要はありません。

同様に、このナンセンスをしないでください:

/*set the value of the age integer to 32*/int age = 32;

それでも、コード自体に何をしても、説明のコメントが必要な場合があります。

通常、これは、直感的でないソリューションにコンテキストを追加する必要がある場合に発生します。

Lodashの良い例を次に示します。

function addSetEntry(set, value) { /* Don't return `set.add` because it's not chainable in IE 11. */ set.add(value); return set; }

また、多くの検討と実験の結果、問題に対する一見ナイーブな解決策が実際に最善であることが判明する場合もあります。これらのシナリオでは、他のコーダーがあなたよりもはるかに賢いと思ってコードをいじり始め、あなたのやり方がずっと最善の方法であることに気付くのはほぼ避けられません。

時々、他のコーダーがあなたの将来の自分です。

そのような場合は、みんなの時間と恥ずかしさを節約してコメントを残すのが最善です。

次のモックコメントは、このシナリオを完全に捉えています。

/**Dear maintainer: Once you are done trying to 'optimize' this routine,and have realized what a terrible mistake that was,please increment the following counter as a warningto the next guy: total_hours_wasted_here = 42**/

Again, the above is more about being funny than being helpful. But you SHOULD leave a comment warning others not to pursue some seemingly obvious “better solution,” if you’ve already tried and rejected it. And when you do, the comment should specify what solution you tried and why you decided against it.

Here’s a simple example in JavaScript:

/* don't use the global isFinite() because it returns true for null values*/Number.isFinite(value)

The Ugly

So, we’ve looked at the good and the bad, but what about the ugly?

Unfortunately, there are times in any job where you’ll find yourself frustrated and when you write code for a living, it can be tempting to vent that frustration in code comments.

Work with enough code bases and you’ll come across comments that range from cynical and depressing to dark and mean spirited.

Things like the seemingly harmless…

/*This code sucks, you know it and I know it. Move on and call me an idiot later.*/

…to the downright mean

/* Class used to workaround Richard being a f***ing idiot*/

These things may seem funny or may help release a bit of frustration in the moment, but when they make it into production code they end up making the coder who wrote them and their employer look unprofessional and bitter.

Don't do this.

If you enjoyed this article, please smash the applause icon a bunch of times to help spread the word. And if you want to read more stuff like this, please sign up for my weekly Dev Mastery newsletter below.