コード内コメントの記述方式

コード内のコメント（コメントアウト）で可読性を上げたいのですが、便利なコメントの書き方とか、こういうの書き方があるという情報がまとまったWebページ・書籍等はありませんでしょうか？
また、皆さんはどういう風に書いてるとか決めておられるのでしょうか？

人によって、会社・プロジェクト、言語によって、慣例のようなものはあると思いますが・・・

ちなみに私は主にjavascript、たまにJavaやObjective-Cを書いていますが、

１ファイル内での大まかな分類や特徴的な部分・重要な部分には

javascript
1////////////////////////////////////////////////
2//  Aに関する処理
3////////////////////////////////////////////////

ここからbという処理を開始するということと、細かい説明はこのような感じで書いています。

javascript
1////////////////////////////////////////////////
2//  Aに関する処理
3////////////////////////////////////////////////
4bSampleFunction: function() {
5    /* bの処理 */
6    // b1を取得する
7    var b1 = this.getB1();
8    // b1を出力する
9    console.log('b1の結果 : %d', b1);
10}

特にこの、細かい部分のコメントは記述方法に困っています。そもそもメソッドを短くするといった基本的な事はもちろんですが、コメントの記述方法は結構可読性を左右すると思います。
にも関わらず、あまり考えたことがなかったので質問させていただきました。
よろしくお願いいたします！

行動規範の内容に同意します

回答2件

一つの方法としてDoxygenやJSDocのようなドキュメント自動生成ツールにあわせるというのがあります。ツールや言語にもよりますが、ソースコードから自動的にAPIのドキュメントが作れるという利点があります。Google JavaScript Style Guide#7 JSDocではJSDocを推しています。

また、/* */と//の使い分け等はAirbnb JavaScript Style Guide#Commentsですと、複数行なら/* */、単行なら//としています。その他、空行を入れる、空白を入れるなどもルール化しています。

また、どんなコメントを書くかですが、次の三つと考えられます。

クラスや関数の説明

クラスや関数の概要、引数、戻り値などの説明を定義の前に書いておく。
2. 処理が必要になる理由や部分的な補足などの注意事項
その処理がなぜ必要になるかが前後からわかりにくかったり、渡すパラメーターがなぜそれなのか補足しないと読み取れない等の注意事項をその処理の手前に書く。
3. 問題となっている点や改善すべき点 (TODO:やFIXME:等とともに)
バグがあるがすぐに直せたない所、パフォーマンスの改善が必要なところ、まだ実装していないが将来実装する予定の所などの手前に備忘録として書いておく。

これ以外に、1ファイルだけのプログラムやライブラリですと、ファイルの先頭にプログラムの概要やライセンス情報を書いておきます。これはコードのためのコメントと言うよりREADME等の代わりという形です。

学習目的などで無ければ、一般に処理の内容自体を単に書くことはよくないとされています。理由としては、

コードをみれば何を処理するのかわかるので、冗長である。
コメントが必要なぐらい、何をやっているのかわかりにくい複雑なコードは悪いコードである。

とされるからです。

他にもここで紹介されているGCPがあります。とにかく目立ちたいというのであればありかもしれません…。

投稿2016/12/30 04:41

raccy

総合スコア21735

mit0223

2016/12/30 07:12

＋しましたし、ここにかかせてください。 > 一般に処理の内容自体を単に書くことはよくないとされています。はい、大賛成です。理由を追加させてください。 - コードを修正するとコメントも修正せねばならず保守コストが増大する - バグの原因をさがすためにコードを調べる場合、コメントは信用できないので、結局、コードを読んで確かめることになる（コメントは役に立たない） - エディタの一画面に表示できる行数が減り、可読性がさがる

行動規範の内容に同意します

javaDocのJavaScript版のjsDocというものがあるようです。これに沿ってコメントを書けば、大人数での開発でもメンテナンスがしやすくなりかもしれませんね。
あとは、2つの似たようなコードを比べるときにこんな感じで書いたりしています。
個人的に使っているものなので、あまり役に立たないかもしれませんが...

HTML
1<!DOCTYPE html>
2<html lang="ja">
3<head>
4    <meta charset="UTF-8">
5    <title>タイトル</title>
6</head>
7<body>
8<script src="https://code.jquery.com/jquery-3.1.1.min.js"></script>
9<script>
10    $(document).ready(function () {
11        /*/←ここの*を消したりつけたり
12         alert("1");
13         /*/
14        alert("2");
15        /**/
16    });
17</script>
18</body>
19</html>