プログラミングコード コメントの必要性

何か最近のコメントに対する事柄を検索すると、コメントは基本書かない！見たいな記事をよく見ます。

これは間違いです！

コメントは1行単位で「後で最適化する」とか言うコメントはいりません！

コメントはコードの最初に書きましょう。

PHPのコードを例に下記に記します。

<?php

/*

入力チェッククラス

新規作成者 〇〇　〇〇

新規作成日時 20xx/xx/xx

機能一覧

１．NULLチェック

common_check_func->string_define

２．文字数チェック

common_check_func->string_length

３．数値チェック

common_check_func->string_numeric

４．メールアドレスチェック

common_check_func->string_mail

５．日付存在チェック

common_check_func->string_MyCheckDate

６．過去日付チェック

common_check_func->string_MyCheckDate_old

７．日付比較チェック

common_check_func->string_MyCheckDate_diff

更新履歴

例） 2006-07-20 ○○部に機能追加 LINE-117

*/

というように、コードの冒頭に、そのソースコードが何を書いてるのかを記します。

そしてバグがあった際の更新履歴は付けましょう。

いついつにコードの処理が遅かった為　何行目を修正等です。

これは結構過去に作ったクラスファイルになりますので、ちょっとコメントの書く理由がありすぎるコードとなります。

例えばメイン画面のコードでも、このような感じでコメントを書くべきであると思います。

こういうやり方をした場合、設計書を書く理由がなくなり、大変解りやすいコードが作れます。

作成者の名前を書くのも重要です。フリーランスのエンジニア数は少ない為、過去に行った現場から作成者を割り出し、再度呼ばれる可能性が出てきます。

そして自分の名前も売れます。

たまに作成者を書き換える輩もいますがそれはモラルの低いエンジニアなので相手しなくていいでしょう。

コメントはソースコードの最初の部分に全てを書く。

ソースコード中にいちいち細かいコメントは書かないが正解と私は思います。

たまにこういう方います。

以下　Perlベース

if ( 〇　== 〇 ){

処理　// この処理はとりあえず保留で

処理 // 遅いので後で書き直し

}

こういう方います。こういうコメントいりません。

全部、始まりに全てコードの説明を書き、利用するモジュールの参照先等を書いたりすると尚良いと思います。

/***

アンケート検索、登録、更新　（検索部）

新規作成者 〇〇　〇〇

新規作成日時 2005/7/15

機能一覧

１．開始日時から検索

２．終了日時から検索

３．全一覧表示

４．前のN件ボタン

５．次のN件ボタン

更新履歴

例） 2006-07-20 ○○部に機能追加 LINE-117

機能一覧なんて書くのも良いでしょう。

また、利用しているクラスのパスなども入れるとよりコードを追いかけやすくなるかと思います。

あくまで参考までに。もしかしたら今は、ファイル管理システムgit hubの機能とかで済ませている可能性もあるかもしれません。

でもやはり、ソースコードの冒頭だけは、更新履歴も付けて書いていくのが良いかと思います。

古いエンジニアのたわごとでした。