プログラムを作り慣れていない人／作れるけど時間のかかる人はコメント文を有効利用してみるのはどうだろう

あくまでソフトウェアエンジニアに限った話ではあるのですが、そういう人、いると思います。まぁいない方がおかしい...と言うべきでしょうか。エンジニアになればだれでもサクサクとプログラミングができるようになると言うわけじゃないですもんね。

ＩＴに少しでも関与や興味を示さないと、なかなか触れる機会のない技術ですから、なかなか皆が皆、プログラミングに慣れ親しんできたと言うわけでもないでしょう。

でも、それが言語の１つであり、またプログラム言語と言うものが人間のために用意されている（コンピューター寄りの言語（アセンブリ言語）では人間が解するのが相当難しいから、わざわざプログラム言語が用意されているんです）以上は、実は日本語からの翻訳だって苦も無くできるようになっているはずです。

どのプログラム言語にも大抵用意されている「コメント文」を活用することがこれにあたります。行コメントなどは実は初心者の人たちにとって、非常に有用だったりします。

もし、プログラミングを始めたばかりの方で、頭の中でなかなか設計内容が整理できず、またプログラムへの処理イメージが難航し、モヤモヤしている人がいたら、まずは日本語のコメント文だけを先に書いて、目の前で整理してみましょう。

たとえば、次のような感じです。

// 標準入出力ヘッダを宣言する。
// int型の変数ｘ、ｙ、ｚを宣言する。
// 変数ｘに10を代入する。
// 変数ｙに０を代入する。
// 変数ｚに５を代入する
// 変数ｘの数分だけ、変数ｙの中に変数ｚの値を加算する。
// 変数ｙの値をコンソールに出力する。

そうすると、少なくとも処理の流れが視覚的にイメージできますし、実際に「処理すべきことが不足していないか」日本語レベルで確認できます。あとは、関数や制御文を思い起こし、あるいは調べながら、行間にプログラムを埋めていくだけです。

たとえば、一般的な C言語 であれば、

// 標準入出力ヘッダを宣言する。
#include <stdio.h>

// int型の変数ｘ、ｙ、ｚを宣言する。
int x, y, z;
// 変数ｘに10を代入する。
x = 10;
// 変数ｙに０を代入する。
y = 0;
// 変数ｚに５を代入する
z = 5;

// 変数ｘの数分だけ、変数ｙの中に変数ｚの値を加算する。
// for( int i = 1; i <= x; i++) { でも可（一般にはやらないけど）。
for( int i = 0; i < x; i++) {
　　y = y + z;
}

// 変数ｙの値をコンソールに出力する。
printf( y );

と言った感じです。頭の中だけでイメージすると、思い込み等による抜け漏れが発生する可能性もありますが、その可能性すらも完全にゼロにすることが可能になります。コーディング作業のプロセス品質を高い水準で維持できるというわけです。

実はこれ、私が新人の頃から"ある条件"を満たしている場合に限り、推奨している品質保証対策の１つです。私自身がエンジニアとして活動する時でも、必ず実施するようにしてきました。どんなに技術的に簡単なプログラムであってもです。

ヘッダーコメントなどを書く場合は、設計書名やシート名、よほど変更がなさそうな場合は章・項なども記載しておくことがあります。

なぜなら、私はこのコメント行を、ただのプログラミング支援機能ではなく、

　担当者間、プロジェクト間の
　コミュニケーション品質を保証するための取組み

と言う位置づけで活用しているからです。成果物品質を保証するうえで、大切になってくるのが「トレーサビリティ」です。つまり、このプログラムが表している処理の流れ、命令の流れは、「どの設計書の、どの部分を翻訳したものなのか？」が後で読むかもしれない人たちに、正確に伝わる必要があるのです。

そうしなければ、いずれコミュニケーション齟齬を起こし、どこかで大炎上することになりかねません。その時、苦労し、後悔するのは、自分自身ではなく、お客さまか、他のエンジニアか、あるいは次に受注するであろう別の会社のエンジニアかもしれないというわけです。

「今さえ良ければいい」「自分さえ良ければいい」ではなく、そういった潜在的な問題を、将来にわたって起こさないようにするため、モノ作り作業の品質を向上しなくてはなりません。

これは、ソフトウェア品質（ISO/IEC 9126-1 または ISO/IEC 25010）でいうところの要求品質特性の１つ

　「保守性」あるいは「移植性」

に大きくかかわってくる品質の考え方です。

ちなみに"ある条件"とは、

　「このコメント行の元となる設計がしっかりと行われているか否か」
　「ベースラインとなる設計書が存在しているか否か」

です。もちろん、設計が行われていてもいなくても、どちらにしてもコメントの記述自体はやった方が良いものではあるのですが、あくまで本質的に求められているのは"トレーサビリティ"の確保なので、トレース元となる設計がもしも存在しないのであれば、必要最低限以上まで無理に行う必要はありません（無理にすればスケジュールが破綻します）。

以前は「詳細設計書」と言う、プログラムをそのまま日本語で書いたような設計書が当然のようにありましたので、これをそのままペタっと貼り付けて、全部コメントにし、そこからプログラムを起こす...と言うことをやっていました。

上図（HIPO図）は一例ですが、形式はフローチャートでも、シーケンス図（UML）でも、なんでもかまいません。あー…でも、上図のように文章化されてしまっていた場合の方が、コメントにはしやすいかもしれませんね。

意外と、当時から周囲のエンジニアは誰もしていなかったので、あまり世間では広く活用されていないのかもしれませんが、初心者であれば、慣れるまでそういう手法もあることを知っておくといいでしょう（なにより、自分の頭の中を整理するのに役立ちます）。

ただし、クライアントサイドで実行されるスクリプト言語は、対象外です。コメントサイズもトラフィックに影響を与えるため、時間効率性が低下しかねません。

昨今ではアジャイル（っぽいもの）がもてはやされ、台頭していく中で、設計書をあまり作成しない進め方を推奨するエンジニアが増えてきました（別にアジャイルはドキュメンテーションしなくていい開発モデルと言うわけじゃないんですけども…）。

今どきのエンジニアの中には

　「詳細設計なんていらねぇ」
　「あんなのやるだけ無駄」
　「さっさとプログラミングした方が早い」

と言い出す人が目立つようになってきているように感じます（そうでない、常識的なエンジニアもまだまだたくさんいるとは思いますが）。

もちろん、自信ありげにそう言う人たちだけに限って言えば、あまり大きな問題を起こすこともなく、十分な品質のプログラムを作成できるのかもしれません。ですが、それはあくまでも属人的な手法の範疇の話です。世の中のエンジニアすべてがそうであると言うわけではありません。

世の中の大半のエンジニア、駆け出しのエンジニアすべてにとって、詳細設計の存在が本当に不要なものなのか、無くても品質上に何も影響を与えないものなのかをしっかりと考えて、ソフトウェア開発アーキテクチャを構築してもらえればいいと思います。

その決断には、お客さまのお金と、所属する会社の信頼と、多くのメンバーの人生とを背負う責任があると言うことを肝に銘じておきましょう。