他人が読めるプログラミングコメントの書き方

プログラミング言語を学ぶと、どの言語でも必ずと言っていいほどコメントの書き方が初回の方に説明されています。 中級クラスのエンジニアになると、コメントの書き方なんて、どのプログラム言語でもだいたい同じ感じなので、耳タコだと感じる人もいるかもしれません。 でも、コメントを軽く見てしまうと、コメントに泣くかもしれませんよ。 色々なフレームワークやOSSなどのコードを見ていると、コメントが詳細に書かれていることに気が付きます。 そうなんですよ。コメントをルール化しておくと、プログラミングの質もアップするという事に気がつくと、スキルアップにもつながるんですよね。 というわけで、コメントをちゃんと理解してレベルアップしちゃいましょう。

コプログラミングコメントパターン

プログラミング言語のコメントって種類があるのをご存知ですか？ 大き聞く分けて3パターンあります。

1行コメント

言わずとしれた、1行のみのコメントで最も多様されているその場の処理の説明を簡易に書く用です。 // 1行コメント

複数行コメント

上記の1行コメントで書ききれない場合に複数行コメントで書く事が多いでしょう。 /* 複数行コメント ※閉じ忘れに注意しましょう。 */

ドキュメントコメント

あまり知られていないけど、上位エンジニアが書いているコメントがこのドキュメントコメントです。 ドキュメントコメントには、ルールが存在していて、それを理解していると、マニュアルさながらの説明ができるようになります。 要するにドキュメントコメントを書いておけば、書いたプログラミングコードの解説を的確にすることが出来るように鳴るということです。 /** * ドキュメントコメント * 開始が、/（スラッシュ）と*（アスタリスク）２つになっているトコロがポイントです。 * 途中行は、スペース+*で、インデントをあわせている点がミソです。 * 終了は、複数行コメントと同じですが、インデントをあわせるというのも要注意です。 */

言語別コメントの書き方

javascript, PHP, Java, C, C++, Go

// 1行コメント /* 複数行コメント */ /** * ドキュメントコメント * @param 仕様記載 */

Ruby, Shell

# 1行コメント # 複数行コメント # この言語にはコメントが1種類しかありません。 # ドキュメントコメント # @param 仕様記載

Python

# 1行コメント ''' 複数行コメント シングルクォートまたは、ダブルクォート３つに囲まれると複数行のコメントが書けます。 ※マークダウンの書き方に似てますね。 ''' ''' ドキュメントコメント param: 仕様記載 '''

HTML

<!-- HTMLには複数行コメントしかありません --> <!-- << div.content --> <div class='content'> <p>開始と終了をわかりやすくselectorで書くパターンもあります。</p> </div> <!-- div.content >> -->

CSS

/* CSSは複数行コメントしかありません */ /** * ドキュメントコメント * @param 仕様記載 */

コメント・ルール化思考

言語別で見ると、コメントの書き方ってまあまあ似たような書き方をする言語が多い事に気が付きます。 すべてのプログラム（コーディング）言語でのドキュメントコメントをルール化させておくと、かなり有意義な記述になると思います。 独自ルールではなく、色々な言語のコーディング規約を集約した形で、誰でも読めるというルール化が重要かもしれませんね。

ほぼ共通ルールで使えるコメント・コーディング規約

プロセス（処理）

// 1行で完結に書く ※文章っぽくしないのがポイント

クラス・メソッド

/** * @ver [型] 説明 * @param [型] 引数の変数名 説明 * @return [型] 説明 */

プログラムファイル

/** * @version 1.0.0 * @create 2023.09.01 * @author Yugeta.Koji * @link https://myntinc.com */

言語別ドキュメントコメント規約リンク

参考までに、色々な言語のコメントコーディング規約や便利ツールなどのリンクを貼っておきます。 Javascript：JsDoc PHP：PHPDocumentor Java: Javaコーディング規約 ソースコード・ドキュメンテーション・ツール: Doxy.gen