32章 読めばわかるコード

Overview

ドキュメントの全体像の説明とコメントについて

32.1 外部ドキュメント

ユニット開発フォルダ(UDF)

クラスやパッケージ、コンポーネントに関する非公式ドキュメント

チーム内で利用される非公式なドキュメント

詳細設計書

クラスまたはルーチンレベルの設計上の決定事項、検討された代替手段、選定理由が記載されたもの

IPAの資料

32.2 ドキュメントとしてのプログラミングスタイル

読みやすいコードを書くことでドキュメントが不要になる

32.3 コメントを入れるか入れないか

ソクラテスの寸劇

コメントはある程度役に立つはずだが、使い方を誤ると害になる

コードを読めばわかることではなく、意図や抽象化したものを書くべき

擬似コードプログラミング(PPP)を行うことで、コメントを書く時間を短縮できる

自分の開発現場の話

PHP Docsコメントは書く

Jetbrainsで自動生成してくれるものも生成しておく

32.4 効果的なコメントのポイント

32.4.1 コメントの種類

コードの繰り返し

コードの説明

コードを改良したほうが良い

コードの目印(マーカー)

アノテーションコメント(TODO, FIXMEなど)のこと

チーム内で運用ルールが決まっている場合には役に立つ

コードの概要

1,2行でまとめてあると作成者以外が修正する際に役に立つ

コードの意図の説明

プログラム作成者の意図を理解するのは難しいので、コメントがあるとよい

コード自体では表せない情報

著作権や守秘義務、バージョン情報、関連リンクなど

コード自体では表せない情報、コードの概要、コードの意図の説明は完成コードにあってもよい

32.4.2 効率的なコメントの作成

変更で壊れたり変更を思いとどまらせたりしないスタイルを採用する

…や空白を揃えるなど

目的に応じてコメント構文を使い分ける

PPPを使ってコメント作成の所要時間を短縮する

コメントを開発スタイルに組み込む

コメントを書くことに注意が削がれている場合には、設計がうまくいっていない場合がある

パフォーマンスはコメントを避ける理由にならない

昔は問題になったが、ビルド時に除去するなどして解決できる

32.4.3 コメントの最適な数

コメントの数よりも効果的かどうかに重点を置くべき

IBMの調査では10ステートメントに1個コメントがあるとわかりやすくなるとのこと

32.5 コメントテクニック

32.5.1 行のコメント

code: (php)

<?php

$fuga = hoge(); // 行末コメント

好き勝手なコメントを書かない

行末コメントはなるべくかかない

データ宣言の注釈

ブロック終端の目印

32.5.2 コードの段落のコメント

コードの意図レベルでコメントを書く

ドキュメントの焦点をコード自体に合わせる

コメントよりもコードを先に確認されるので、先にコードを治す

段落のコメントでは、方法ではなく理由に焦点をおく

コメントを使って読み手にその先にあるものを予測させる

コメントを増やしすぎない

意外な事実を文章化する

後述の技巧に走っているのではないことを示す

略語を避ける

メジャーコメントとマイナーコメントを分ける

広義と狭義のコメントをつけるとわかりやすくはなくがコメントを書くハードルが上がるので簡単な方法を考える

メジャーコメントの処理を独自ルーチンに分ける

言語や環境のエラー、ドキュメントにない機能

プログラミングスタイルに違反する理由

技巧に走っているプログラミングは修正する(コメントをつけない)

だれかが「これは凝ったコードだ」と言ったら、筆者には「これはひどいコードだ」と言っているように聞こえる。あなたが凝っていると感じるコードは、他人には理解できないだろう。それほど凝っているようには見えないコードでさえ、そのトリックを見たことがない人にとっては、複雑すぎて理解できないように思えるだろう。「これは凝りすぎかな」と考えているとしたら、それは凝りすぎである。単純になるように書き直す方法は必ず見つかるので、コードを書き直そう。コメントを付ける必要ないほど良いコードにし、コメントを付けてさらに良いものにしよう。

32.5.3 データ宣言のコメント

変数名では説明できない変数の特徴を説明する

データについている注釈が、そのデータを使用するプロセスの注釈よりも重要であるという結論を下している。

数値データの単位、数値の許容範囲、入力データの制限をコメントで説明する

これは後から出てくるけど、アサーションやバリデーションのコードを見ることでで解決したほうがスマートなのではという感想

コードの意味をコメントで説明する

twadaさんの「コードには How　テストコードには What　コミットログには Why　コードコメントには Why not」を書くというやつだ

フラグをビットレベルで文書化する

フラグに細かく意味を持たせると割とつらい

変数に関連するコメントを変数名で区別する

この辺はコメントの入れ方とかも運用で決めとかないとカオスになりそう

32.5.4 制御構造コメント

この章はそうだねっていう感じでした

そもそもコメントを使わないと伝わらない制御構造はダメなんじゃないかっていう気がする

ネストの終わりを示すコメントは、今だとかっこの対応はIDEとかで分かりやすいし見たことないな

これが必要＝ネスト深すぎる問題もありそう

各ループの終端コメントはコードが複雑であることの警告と受け止める

32.5.5 ルーチンのコメント

一番最初に出てきた悪い例みたいなコメントは、かつてはルール化されていたのだろうなーくらいな感じで見ていた

引数は宣言時に文書化する

Javadocなどのドキュメント生成ユーティリティを利用する

このためにコメント書くっていうのはまあわかる（使ったことはないけど）

ルーチンのグローバルな効果を文書化する

ルーチンがグローバルデータに対して何を行うのかを正確に説明する

32.5.6 クラス、ファイル、プログラムのコメント

クラスやファイルの一般的なガイドラインについて書かれていることは、必ずしもコメントとして残さなくても、クラス図とかREADMEとかで補完しても良さそうに思った。

プログラムの文書化のための本のパラダイム

ここはプログラムに関する情報の構造化と整理の方法について、一般的な書籍の構成要素を参考にすると良いですよ、という話

プログラムの構成を上位レベル（概要）と下位レベル（詳細）で説明する文書を用意することが重要である

32.6 IEEE規格

要件定義や開発についてのIEEE規格があることを初めて知った。

32.6.4 規格の概要

IEEE Software Engineering Standards Collection

規格ごとに、ドキュメントの概要、概要の各要素の説明、その要素の理論的根拠が含まれている

こういうの、大手のベンダーとかは注力している人がいそう

こんな感じの資料見つけた（やはり大手だった。NECさん）

32.7 参考資料

一番最初に紹介されてる本はちょっと気になる

なんか自分の中でコード書くときの手札が全然足りてない感じがあって、それはコード書く量もそうだけど読む量も足りてないからだなっていうのがあり、コツコツやってみようかなーと思っているという話です

32.8 まとめ

コメントをつけるかどうかは重要な問題である。

ソースコードには、プログラムに関する重要な情報のほとんどが含まれていなければならない。

良いコードはそれ自体が最高のドキュメントである。

コメントは、コードでは言い表せないコードの何かを、概要または意図のレベルで説明するものにする。

基本的にはコードで表現するようにするべきで、コメントだらけになるようだったら設計や実装を見直すべき

コメントスタイルによっては、短調で機械的な作業を延々と繰り返さなければならないものがある。保守作業が容易になるようなスタイルを作成しよう。