読みやすいコードを追いかける
コードを読む際に、冗長的で長いコードを読むのは辟易するだろう。
そして、それを修正しなくてはならないとなったら。。。（どこを直してもバグが起きるしかしない）
逆に、短くてすぐに理解できるコードだったらどうだろう？
修正箇所の特定も簡単で、安心して修正ができる。
読みやすいコードとは、短くて簡潔なものだ。
短くて簡潔にするためには、少ない部分に様々な意味を詰め込んでいく必要がある。
読みやすいコードを書くために心ががけたいことについて説明する。
名前に情報を埋め込む
変数名に短いコメントで汎用的な名前を利用すると、
コードを読む人間にとって想像し難く、人によって意味を取り間違えたりする。
他人から想像しやすい名前を利用することで、わかりやすく読みやすいコードが実現できる。
変数には名詞を、関数には動詞を
Boolean型の変数にはis+名詞
配列は複数形、取り出した値は単数形
変数が値の場合は、単位などを入れる
コードにコメントを書く
過去の自分がコメントを書く際に気を付けていたこと
他人がコードを読んだときに、誤解されやすいかどうかを考えながらコメントを書くべきである。誰が見ても自明なものにコメントを付けるよりも、自分しかわからない仕様になっている部分に簡潔なコメントをつけることが大切だ。
書き手の意図を読み手に知らせること
コメントを記載することでコードの可読性は格段に高まる。
コメントは「この処理はこんなことをやってますよと説明する」ために書くのではなく、
「なぜ、この処理なのか？」「どうして、この実装になったか？」など、自分の意図を伝えるために記載しておくのが正しい。そして、読み手とは他人だけでなく、未来の自分に向けて記載することも忘れてはならない。
開発中に未来の自分のために書くコメント
コードを書く人間が自分で、テストをする人間が自分だったとしても、2人が同じ人間だと思ってはいけない。未来の自分は、過去の自分に対して常に「なんてひどいコードなんだ！！」と思う人種なのだ。そして、大概のケースで、書いたコードの第一読者は数時間後とかの未来の自分だ。だからこそ、コードを書きながら未来の自分に向けてコメントを残しておく必要がある。
未来の自分に向けたコメントPoV
#1 コードの欠陥につけるコメント
> コードを書いていると、改善が必要、コードが未完成、リスクがあるコードとか、
> 書きながら様々な気持ちに苛まれる。そして、すぐには解決できないものもある。
> そういった開発中の気持ちはコードに以下のような記法で残しておくとよい。
// ToDo: 【性能チューニング要】もっと高速なアルゴリズムを使う
// ToDo: 【未完成】○○という箇所が未実装
// FIXME: 【問題あり！】○○という既知の不具合がある。
// HACK: 【気になる】あまりコードがきれいじゃない
// XXX:【危険！】○○な危険がある。
#2 処理の要約コメント
> コードのまとまり毎に要約を記載する。
> また、全体処理概要を文頭に記載することも大切。
> このとき、コメントすべきでは「ない」ことにコメントを付けないように
> コードからわかること以上の情報を記載するようにする。
#3 ライダーズブロックを乗り越える
> 口語調で未完成でいいのでコメントを書く。
> コードを書きながらコメントを記載するのは至難の業。
> 一度書いてみて文章を推敲していく作業が大切。
> 推敲作業については、コメントの書き方PoVを参照。
#4 嵌りそうな罠や記憶喪失を避けるためのコメント
> 間違えて使われそうなもの(外部コマンド呼出や複雑にネストされた処理,特殊な実装)など、
> 実装時に調査を要したものはその調査の経過を記録しておく。
// 外部のAPIを呼び出している（リクエスト内容については資料○○を参照)
// ○○と××の実装を比較したところ○○の方が処理が1.1倍速かった。
他人のためにコメントを書き換える
大抵の人間は、開発しながらコメントを記載する。コメントを記載しながら、コードを書き終えて、テストし終えたら、Gitにコミット！というのが、よくある流れだ。（稀にテストせずにGitに上がるコードもいるが...）しかし、未来の自分のために書いたコメントを見返しながら、誰かのためのコメントに書き換えよう。その中で、コードのリファクタリングの機会やウォークスルー的なセルフコードレビューの機会を得られる。
他人のためのコメントPoV
#1 コードの欠陥の改修
> ToDoとしているものや、XXXとなっているものが残っていないかを確認する
#2 定数にコメントをつける
> なぜその定数があるのか、どんな働きがあるのかを記載する
#3 ひどい名前を改名する
> 優れたコメント+ひどいコード < 優れたコード という考え方。
> 補助的なコメントを書くくらいならば、ひどい名前は改名する
#4 質問されそうなことを想像する
> 他人が質問してきそうな部分に、質問コメントを挿入する。
> その回答をコメントとして残しておく。
> （その後、質問コメントは削除しよう）
#5 正確で簡潔なコメントに推敲する
> 人によって意味の捉え方が異なる単語の利用を避け、具体化する。
> 詳細は、コメントの書き方PoVを参照。
コメントは領域に対する情報の比率が高くなければならない
正確で簡潔なコメントを書くことで、読者にとってより意味のあるコメントを心掛けたい。
コメントの書き方PoV
// HACK:羅列してるだけなので、もう少し自分の哲学や意図を加える。
#1 コメントを簡潔にしておく
#2 あいまいな代名詞は避ける
#3 歯切れの良い文章を書く
#4 関数の動作を正確に記述する
#5 入出力のコーナーケースに実例を使う
#6 コードの意図を書く
#7 名前付き引数のコメント
#8 情報密度の高いコメントを使う
トレーニングとしてコメントを書いてみる
弊社の新人は、物凄い技術に詳しい人もいれば、文系出身で初めてコードを書きますという人まで幅広く入ってきます。
即戦力ならばそのままタスクを振ればよいのですが、初心者エンジニアにはそうはいきません。（とはいえ、エンタープライズの古代呪文を含めて即戦力という人材は中々貴重だと思いますが。。）
月並みですが、コードは書けることも大事ですが、読めることも大切です。
そのため、新人エンジニアには、ソースコードと設計書を渡してコードを読みながらコメントをつけるというタスクをやってもらっています。その中で、コメントを書くコツみたいなものを身に着けてもらいつつ、プログラミングの文法を調べてもらい、徐々に、コードが書けるエンジニアになってほしいなと思っています。
また、システムのソースコードを読んでもらうことで、プロジェクトのシステムを理解してもらい、1つでもわかる/得意なシステムを見つけてもらえることで、そこから彼らのキャリアを歩んでもらえることができるかと思います。
（もしかすると、システムのリファクタリングが叶うかもしれないですしね。）
コードにコメントを書いてみるトレーニングは、意外にプロジェクトに恩恵をもらたしてくれます。是非、お試しください。
重複を避けた構造を作る
コードやコメント、ドキュメントなどコードを構成する文字はいくつかある。
その中で、コードの繰り返しはもとより、意味的にコードとコメントが重複すると、同じ長さのコードでも意味合いが薄れてしまう。
DRY原則を守る
Don't Repeat Yourshelfの略。
OAOO(Once And Only Once)という「コードを重複させない」という考え方と混同されることが多いが、DRY原則はコードの中だけにとどまらず、「システム内において情報を重複させない」という考え方である。
( 繰り返しのPoVは目的が一致するかどうか。）
#1 作業の重複は自動化で防ぐ
#2 ロジックの重複は抽象化で防ぐ
参考文献
リーダブルコード
「リーダブルコード」を読む (第5章「コメントすべきことを知る」第6章「コメントは正確で簡潔に」)
新卒エンジニアがリーダブルコードを読んでみた
達人プログラマー
あなたはDRY原則を誤認している？
プログラマが知るべき97のこと
プログラマが知るべき97のことまとめ:【29】DRY 原則
編集履歴
2022.11.01 3年目になって新人の学習タスクにコードリーディングをしながらコメントを加えてみようというタスクを出した際に、コメントについて整理したいなと思い追記。
2022.11.04 序論と変数名についての記載を追記。
2022.11.08 DRY原則について記載
（以下、ログ）
リーダブルコードで大切だなぁと思った部分
エンジニア1年生の僕はコードの正しい書き方がわからなかったので、
とりあえず、伝家の宝刀リーダブルコードを読んでみました。
大切だなぁと思った部分をまとめておきます。
リーダブルコードはぱっと見で読みやすいコードを書くための
Tips集というようなイメージでいます。
そのため本記事ではぱっと見のコードをわかりやすくするものをまとめました。
外観に関して
コードをパッと見たときに、カタマリになっていて、一貫性があることを意識したい。
コードを段落に分けることや、縦の列が綺麗になっていることはもちろん、
適宜、メソッドを用いたり、変数の並びに意味をもたせながら美しさを意識する。
変数名について
変数名は明確な動詞や名詞を用いて、具体的に定義するべきである。
単語を意識するだけでなく、大文字やアンダースコアに意味を持たせることで、
より分かりやすい変数名を付けることができる。
コメントについて
他人がコードを読んだときに、誤解されやすいかどうかを考えながらコメントを書くべきである。誰が見ても自明なものにコメントを付けるよりも、自分しかわからない仕様になっている部分に簡潔なコメントをつけることが大切だ。
コードの長さについて
ライブラリを利用するなどして、コードの長さを短くすることを心がける。
そのためには、ライブラリに目を通しておくことが必要だ。
また、式や関数を短くすることや、変数のスコープを小さくすることでも
短いコードを書けるようになる。
関数について
一つの関数には一つのタスクを割り当てる。
そうすることで、関数の名前付けがしやすいし、コードの独立性が保たれ、
より意味を持ったコードが書きやすくなる。