はじめに
私たちエンジニアは、他人にソースコードでは表現できない意図を伝える為にコメントを書き残します。その内容は、意味不明な特殊仕様の説明、ほとばしる熱いパトスからこぼれた愚痴、新年を迎えると壊れるヨハネの黙示録であったり、まさに百鬼夜行です。人は、なぜ不必要なコメントを書き残すのか、実例と共に考えたいと思います。
実例と解説
@FUCK
// @FUCK
for ($i = 0; $i <= 3; $i++) {
for($j = 1; $j <= 5; ++$i) {
for ( $k = 0; $k <= 8; ++$i) {
for ( $l = 1; $l <= 13; $i++) {
...
}
}
}
}このコメントを書き残した人は、この多重下請け構造のような for 文に対してかなりイライラしたのでしょう。
実際、テキストエディタの画面を横スクロールしないと何を書いているのかわからないぐらい酷いものでした。
さらに include 式で外部ファイルを複数跨いでいる状態です。
for 文の階層は闇の深さ、そうまさに「アビス」です。
アビスには「呪い」があって、深層にあるスパゲティコードを読み解き、リファクタリングして帰還した開発者は重度のストレスによってハゲ散らかす可能性があります。
将来的に PHP の新機能として是非、FUCK アノテーションを実装していただきたい。
時限式アポカリプス
// 来年動かなくなるから
if ($kotoshi < 2020) {
...
}2021 年 1 月 1 日が「怒りの日」であろうことが預言者によってコメントされています。
システムが滅びた後、責任者がプロジェクトに関わる全ての人間を会議室に復活させ、その行いを審判し、会社で永劫の残業と徹夜の責め苦を加えられる開発者を選別する…！
これを「最後の審判」と申します。
預言者は蒸発、又は退職していることが多いです。
コメントスプレマシスト
// 配列を宣言しています。
$users = [];
$articles = [];
// 配列に記事データを代入しています。
$articles = getUsers();
// 配列に会員データを代入しています。
$users = getArticles();
// もし記事データがなかったら処理しません。
if (!$users) {
// もし会員データもなかったら処理しません。
if (!$articles) {
...
}
} // ここで処理が終わります。見たらわかるレベルのコメントを書き散らかすタイプの生真面目な人がいます。
このタイプの人は、ソースコードにコメントを絶対に書くべき！いいから黙って書くべき！お前もコメントを書くべき！書かないヤツは淘汰するべき！べき！べき！べき！という考えになってしまっていることがあります。
因みに、「〜べき」が口癖な人は多様性を認めない差別主義者が多いそうですね。
そもそもコメントを書かないと他人に意図が伝わらないコーディングが悪いのであって、いちいちコメントを書くよりも他人が見て最速で理解できるようなコーディングを意識することの方が重要なのではないでしょうか。
その上で「誰がソースコードを読むのか？」というところに合わせてコメントで意図や概要を書いてあげれば良いんじゃないかと思います。
また、仕様変更や不具合によってコードを修正した後にコメントの更新を忘れてしまい、コードとコメントに矛盾が生じて実例のような嘘コメントになってしまったり、コメントの管理に工数を消費してしまったりとデメリットもあるので適切なコメントを心掛けたいところですね。
前前前任者
//TODO: A さんと B さんここよろしく(^^)
//TODO: C さん、確認よろしくお願いします。
//TODO: D さんここよろしくー離職率の高い会社では顔も知らない先輩達の TODO コメントがたくさん残っていることがあります。
即日解雇、蒸発、退職勧奨などあったのでしょうか。
実際に、TODO コメントが抽象的でやらなければならないことが書かれていない、仕事の伝達が口頭のみだったのでチャットに情報を残していない、バージョン管理システムやプロジェクト管理ツールを導入していない、仕様書や引き継ぎ資料が全く存在しない、クライアントが丸投げで納品物を確認しないという隙を生じぬダメの多段構えになっているプロジェクトによく遭遇します。
やんごとなき事情があったのかもしれませんが、任された側としては証跡を残さない仕事のやり方をされると本当に困ってしまいます。
謎コロンビア
// ,.へ
// ___ ﾑ i
// 「 ﾋ_i〉 ゝ 〈
// ﾄ ノ iニ(()
// i { ＿＿＿_ | ヽ
// i i ／__, , ‐-＼ i }
// | i ／（●) ( ● ) ＼ {､ λ
// ト－┤. ／ （__人__） ＼ ,ノ ￣ ,!
// i ゝ､_ | ´￣` | ,. ‘´ﾊ ,!
// ヽ、 ｀` ､,__＼ ／” ＼ ヽ／
// ＼ノ ﾉ ﾊ￣r/:::r―–―/::７ ﾉ ／
// ヽ. ヽ::〈； . ‘::. :’ |::/ /
// `ｰ ､ ＼ヽ::. ;::：|/ ｒ’”
// ／￣二二二二二二二二二二二二二二二二ヽ
// | 答 | エ ラ ー │|
// ＼＿二二二二二二二二二二二二二二二二ノシステムでエラーが発生すると画面にアスキーアートが出力されたり、コメントでアスキアートと一緒に仕様が書かれていることがあります。
コメントでアスキーコードを書くことが目的になってしまい、大事な仕様詳細を書き忘れてしまうお茶目さんもいます。
受託案件でやっちゃダメですよ。
凶兆
// API仕様書には嘘が多いから気を付けて。このようなコメントが書かれている時は保守運用が前途多難であることの予兆です。
システムと連携しているとある大手の API の仕様書が嘘だらけでどうしようもないのでこのコメントが書かれました。
サポートに問い合わせても「如何しようも無いですね」という感じでした、残念ですね。
そもそもレスポンスデータの情報がわからない箇所が多かったので苦笑するしかなかったです。
悪習
// おまじない
let example = ''
// コピペ
exampleButton.addEventListener('click', () => {
...
})脳死コピペプログラマーのあるあるコメントです。
実例のコードはまだマシな方で、コピペ先のコメントがそのままになっていることがあります。
言うまでもなく、インデントやコーディング規約をぶっ壊してそのまま貼り付けてきます。
プログラムをコピペすること自体は悪いことではありません。
ただ、理解しないでコピペすることは悪いことです。
理解放棄の習慣化は脳死コピペプログラマーを爆誕させます。
納期や工数不足の関係で已むを得ない場合があるかもしれませんが、脳死コピペの積み重ねによる制御不能な技術的負債がシステムと人間を壊すということを忘れちゃいけないと思います。
まとめ
人は、なぜクソコメを書き残すのか。
それは人間が感情の動物だからではないでしょうか。
クソコメを書き残す動機は人間の感情です。
その裏側にある真実は劣悪な職場環境、人間関係のストレス、非効率な仕組み、指摘できる技術者の不足など、つまりクソコメは状態や状況などを表しているのではないでしょうか。
もちろん全てのクソコメがそうだと極論する気は毛頭ないです。
ですが、もし、クソコメを書いている開発メンバーに気付いたら「おい、大丈夫か。」と声を掛けてみてはどうでしょうか。
以上です。
おわりに
おちゃらけた記事にしようと書いてみたら真面目な内容になってしまった。
