【開発哲学3_32】〜『CODE COMPLETE第２版 第32章(下巻)』の感想〜読めばわかるコード
感想
ここまでで説明の薄かったコメントの書き方やポイントを通して、
今までの各章で触れてきたコーディングテクニックの総まとめ的な章。
やはり、
疑似コードでコードを書く（第９章）
ルーチンを小分けにする（第７章）
的確な名前を変数や引数、ルーチンにつける（第10、11章）
リファクタリングをする（第24章）
コードチューニング（アンチリファクタリング）が必要な箇所は、なぜ敢えてそうしているかの意図をコメントで残しておく（第25、26章）
など大事だよねえ。
詳細
見出しとしては、
外部ドキュメント
ドキュメントとしてのプログラミングスタイル
コメントを入れるか入れないか
効率的なコメントのポイント
コメントテクニック
IEEE規格
参考資料
まとめ
て感じ。
個人的に、行末コメントは使わない。
コードをまとめたどの本でも、コメントについては大体、
//税込価格を計算する
function sample(){
let num = Browser.inputBox('金額を入力してください'); //単価
const tax = 1.1; //消費税率
let result = num * tax; //税込価格
result = Math.trunc(result); //小数点以下を切り捨て
console.log(result); //計算結果をログに出力
}みたいな感じで、行末コメントで、コメントの説明をしてることが多い。
コードの読みやすさを意識して、
意味のある変数名やルーチン名をつける
だけで、ほとんどコメントすら要らなくなる。
function 税込価格(){
let price = Browser.inputBox('金額を入力してください');
const consumerTaxRate = 1.1;
let zeikomiPrice = price * consumerTaxRate;
//小数点以下を切り捨て
zeikomiPrice = Math.trunc(zeikomiPrice);
console.log(zeikomiPrice);
}その上で、
マジックナンバー対策
効果的な空白行による改行
何か引き継ぎや注意事項のみコメントを残す
をやると、
/**
TODO: 消費税率変更のタイミングで、consumerTaxRateの数値は変更すること。
*/
const consumerTaxRate = 1.1;
function 税込価格(){
let price = Browser.inputBox('金額を入力してください');
let zeikomiPrice = price * consumerTaxRate;
//小数点以下を切り捨て
zeikomiPrice = Math.trunc(zeikomiPrice);
console.log(zeikomiPrice);
}てな感じ。
もちろん、前章のレイアウトとスタイルどおりに、
/**
TODO: 消費税率変更のタイミングで、consumerTaxRateの数値は変更すること。
*/
const consumerTaxRate = 1.1;
function 税込価格(){
let price = Browser.inputBox('金額を入力してください');
let zeikomiPrice = price * consumerTaxRate;
//小数点以下を切り捨て
zeikomiPrice = Math.trunc(zeikomiPrice);
console.log(zeikomiPrice);
}コードごとに１行の改行
ルーチンごとに２行の改行
を挟むと、たしかにより読みやすくなる反面、
処理全体で数行で終われば良いけど大抵、全体が100行とかすぐに超えるから、
使っているPCの画面サイズによっては、
すぐにコードが画面から溢れてしまい、コードを探したり改修するのに、上下左右、縦横無尽にスクロールしないといけなくなって、手間が増えるんだよねえ。
だから、不要な改行は極力入れないようにしてる。
結局、
読みやすさ・改修しやすさ・コードの打ちやすさを総合しながら、
＜自分（や組織）にとって、読みやすいコードとは何か＞
を決めることが大事かなあ。
まとめ
💃コメントは他のテクニックと並行して行うと効果的
コメント数が多すぎても、少なすぎても害になるだけ🕺
↓
それ以外の読みやすいか読みにくいかは、所詮、
本人（や組織）の美意識＝主観
次第。前章でも書いてるとおり、、、。