感想

ここまでで説明の薄かったコメントの書き方やポイントを通して、
今までの各章で触れてきたコーディングテクニックの総まとめ的な章。

やはり、

• 疑似コードでコードを書く（第９章）

• ルーチンを小分けにする（第７章）

• 的確な名前を変数や引数、ルーチンにつける（第10、11章）

• リファクタリングをする（第24章）

• コードチューニング（アンチリファクタリング）が必要な箇所は、なぜ敢えてそうしているかの意図をコメントで残しておく（第25、26章）

など大事だよねえ。

詳細

見出しとしては、

1. 外部ドキュメント

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

3. コメントを入れるか入れないか

4. 効率的なコメントのポイント

5. コメントテクニック

6. IEEE規格

7. 参考資料

8. まとめ

て感じ。

個人的に、行末コメントは使わない。

コードをまとめたどの本でも、コメントについては大体、

//税込価格を計算する
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の画面サイズによっては、
すぐにコードが画面から溢れてしまい、コードを探したり改修するのに、上下左右、縦横無尽にスクロールしないといけなくなって、手間が増えるんだよねえ。
だから、不要な改行は極力入れないようにしてる。

結局、

読みやすさ・改修しやすさ・コードの打ちやすさを総合しながら、

＜自分（や組織）にとって、読みやすいコードとは何か＞

を決めることが大事かなあ。

まとめ

💃コメントは他のテクニックと並行して行うと効果的
コメント数が多すぎても、少なすぎても害になるだけ🕺
↓
それ以外の読みやすいか読みにくいかは、所詮、
本人（や組織）の美意識＝主観
次第。前章でも書いてるとおり、、、。