こんにちはWorkaholicです。
ツイートが少し伸びたので現役エンジニアの観点からソースコードへのコメントや、設計書の重要性について意見を書いて行きたいと思います、
・結論
設計書等のドキュメント類やソースコードにコメントを残すのは必須です。それぞれの記載の粒度は仕事やプロジェクトによって異なるでしょうが、そもそもそれらを無くしてレビューに通る事はまずないでしょう。
納品される成果物として、ソースコードの資産のみでOKという仕事を見たことはありません。
私がツイートの元にしたｲﾝﾌﾙｴﾝｻｰは実務経験が無かったのかもしれませんね。
・なぜ必要なのか？
設計書やソースコードのにコメントを残すの理由としては「保守性を上げる」事にあります。
ソフトウェア・システム開発において最初から最後まで同じ人が同じ役割をもって開発プロジェクトに常駐することなどまずありません。開発フェーズが終了し運用フェーズに乗れば当然人は減りますし、運用フェーズのメンバーが変わることなど日常茶飯事です。そうなれば当然ソースコードを管理する人も変わりますよね？
では新規参入者がそのソースコードを管理する上で毎回すべてのコードを見て理解するでしょうか？
正直それはそれは不可能に近いです。数百数千行もあるソースコードが何十何百ファイルとあるなかで、問題や改修が発生するたびにソースコードの内容を確認するようでは、無駄に時間を喰うばかりか、理解の間違い起こす可能性があります。そのような事をなくす為にも設計書やソースコードにコメントを残すことは必須となります。
・かと言ってもやりすぎもNG
設計書のドキュメントに仕様、処理、改修記録等をキッチリ残すのは大事な事です。ソースコードにも改修記録や何故その処理があるのかを残すのも大事な事です。では分かる処理一つ一つにコメントの残すが正しいか？と言うとそうではありません。そもそも業務用のソースコードであれば可読性も高めるようにすることが記載するべきであればあり、なぜその処理にしたのか一目で分からない処理にこそコメントを残す必要性があります。
しかし一概にコメントを付けるルール等は存在していません。一部ではソースコード全体の10～20%がいいなんて話もありますが、すべてにこの条件を当てはめる事は出来ないと思います。大事なのは作り手以外の人がそのソースコードを見た時に処理の内容がスッと入ってくるように記述できているか？が大事なのです。
初心者ITエンジニアの人はその観点をレビューの際にしっかりと確認してもらうようにしましょう。
流石にこんなコメントを付けているようではやりすぎですね↓
#include <stdio.h>
int main(void)
{
//int型変数a定義する。
int a;
//入力を促すメッセージを表示
printf("整数を入力してください = ");
//文字入力処理
scanf("%d",&a);
//変数aを2で割った余りが0かそれ以外を判定
if( a % 2 == 0 ){
//偶数と判定した際のメッセージ表示
printf("%d は偶数です\n", a);
} else {
//奇数と判定した際のメッセージ表示
printf("%d は奇数です\n", a);
}
//戻り値0を返す
return 0
}
・最後に
「設計書を書く」「コメントを残す」事についての粒度は各プロジェクトできっちり定義されている所もあれば、ITエンジニアに任せている所もあります。そのような場合もでも少なくでも「不要」という事はまずありません。
保守フェーズから入れば過去の内容を踏襲する。新規プロジェクトであれば過去の経験を元に記載を行い、レビューでOKを貰う。その点を心がけるようにしましょう。
コメント