【はじめての輪読会】リーダブルコード4～6章

◆ Live配信スケジュール ◆
サイオステクノロジーでは、Microsoft MVPの武井による「わかりみの深いシリーズ」など、定期的なLive配信を行っています。
⇒ 詳細スケジュールはこちらから
⇒ 見逃してしまった方はYoutubeチャンネルをご覧ください

【5/21開催】Azure OpenAI ServiceによるRAG実装ガイドを公開しました
生成AIを活用したユースケースで最も一番熱いと言われているRAGの実装ガイドを公開しました。そのガイドの紹介をおこなうイベントです!!
https://tech-lab.connpass.com/event/315703/

社内での輪読会のための資料です。今回扱う本は「リーダブルコード」です。最近コメントやコードの書き方についての指摘をいっぱいもらえるのでうれしいです。良いエンジニアになるために名著に入信しています！まだまだ、資料作成の方針を模索中です。より良いブログの形を探すため、新米が中堅になるためのステップアップ記録

1 ご挨拶
2 4章　美しさ
3
- 3.1 メモ
4 5章　コメント
5 6章　コメントは正確で簡素に
- 5.1 メモ
6 終わりに

ご挨拶

どもども！今回は社内輪読会のためのまとめ資料をブログ形式でまとめてみるという取り組みをやっていきます。ども～最近エンジニアのキャリアについて真剣な顔をしながら悩んでいる龍ちゃんです。今回は、社内イベントの話を書いていきます。というか社内イベントで見せるための資料作りですね。

2023/06/08に第一回の輪読会が開催されます。というか今日ですね。「輪読会ってなんぞ？」という方のためにざっくりと説明しておきます。簡単に言うと一冊の本を何人かで読んで意見交換をしていこうや！という会になります。章ごとにファシリテーターを設定して、内容の要約やスパイス付けを行って参加者に説明するのが一般的です。週一で2時間本についてしゃべる時間を持つことはとても良いことです。スケジュール調整に取り組む良い機会でもあると思っています。

発表形式については自由だったので、YouTube登壇系にしてしまうことも手だったなと思っていました。思ったよりも時が早くたってしまったので慣れているブログ形式でシャカシャカ書いています。今回のお題は「エンジニアの強い味方『リーダブルコード』」です。そういえば、昔の記事「コードレビューは学びが多い」で気を付けなければならないことで触れていましたね。やっとで機会が巡り取り込むことができます。今週の僕の担当は「4章～6章」です。さくっとまとめていきましょう。

前回の1~3章は佐々木千奈さんがまとめてくれているので読んでない方はご一読どうぞ！「【はじめての輪読会】リーダブルコード1～3章」

4章　美しさ

タイトルがかっこいいですよね。これ英語だったら「beauty」とかなんですかね？めちゃめちゃシンプルでわかりやすいタイトルですよね。上司に聞いたら「Aesthetics＝美学」だそうです。**かっこよすぎかよ！！**直接的な部分としては見やすさという部分になります。この章でのエッセンスを抜き出しておきますね。

フォーマットは整える
コードの分割（空白・段落）
コードの規則性を保つ（一貫性）

下のコードを見比べてもらえるとわかりやすいかと思います。コードを詰めて配置するよりも適宜分割を入れたほうが見やすいかと思います。次の章でも触れますが、コメントを入れるともっと見やすくなっちゃいますね。『コードの規則性』の部分は複数のコードを書いたときに影響してきます。変数の宣言は上部にまとめるとか、処理はこの辺にまとめるとかそういった話です。

メモ

フォーマットは整える・コードの「列」を整列すればよい：コードフォーマッターを入れよう
命名の規則やカンマの位置をええ感じにする
改行の位置は合わせる
コードの規則性を保つ（一貫性）
宣言-呼び出し-ロジックはこの辺といった規則を自分の中で作って守ろう
空白を作って区切る、段落を分ける
コードの単位で適宜空白を入れる。コメントで注釈をつけるなどをする

5章　コメント

直接的なタイトルはわかりやすいので素晴らしいです。ただのコメントの書き方についてを述べています。この章のエッセンスを下にまとめておきます。

無意味なコメントをしない
意味のあるコメントは大歓迎
読み手の立場になってコメントをする

前提に置いておくべきことを置いておきますね。この章で受け取ったことはこの一文に集約されています。

では悪いコメントと良いコメントの境界はどこだ？という話になりますよね。それは大変難しい問題です。ちなみにいっぱいのサンプル付きで書いてあるのでわかりにくいと思ったらすぐ書籍を購入しましょう。

悪いコメント

悪いコメントの例はわかりやすいと思います。いわゆるくそコメですね。下に並べてみます。

命名からわかることをわざわざコメントしない
単純な処理にコメントを付けるもんじゃない（何でもかんでもコメントは厳禁）
コメントで日記を書かない、お気持ち表明をしない

こんな感じです。悪いコメントをもりもりにしたサンプルを書いてみますね。

// 今日はこのコードを忘れたんやで、いやになるなぁ～ヤバスンギ
// スプレッドシートファイルの取得
const file = SpreadsheetApp.openById(FILE_ID)

こういったコメントは削除で問題ありません。

良いコメント

ではよいコメントとは何でしょうか？とても難しい問題です。まず「良い」ってなんだろうという哲学モードに入ってしまいそうになるぐらいわかりません。それでもええ感じにサンプル書いてあったので下に並べます。

定数はわかりやすい命名とコメントを付ける
全体像の把握をするために処理の塊でコメントつける（目次コメントはあり？）
日本語だけでなく、時にはサンプルを書くことも助けになる
読み手がわかりやすいかどうかが重要、コメントはすべて読み手のために

何よりも重要なのは「すべてのコメントは読み手のために！」という内容だと思います。読み手がわかりやすいか？これで意図が伝わるかどうか？ということを考えながら良いコメントを書かないといけません。

書籍の中で「ライターズ・ブロック」という言葉が出てきました。文章が書けなくなってしまう現象のことだそうです。確かにくそコメントを怒られたりしたら、書くのが怖くなりますよね。僕もブログを投稿したら、Twitterで鋭角なコメントをもらってビビり散らかしました。

でもここで考え方をしょげた方向から良い方向に転換させてください。鋭角なコメントって最高に勉強材料じゃないですか？だって刺さるということはそれが的を得たコメントであるということです。つまり修正すればよいんです。成長の機会なのです！！なので積極的にくそコメントをつけてから考えて修正していきましょう。「とりあえず書く！そして修正」これが大切です。

メモ

無意味なコメントをしない
コードからわかることは書かない（命名でカバーする）
コメントを補足するコメントは無意味→命名を変えたらよいのでは？
コメントは作成の背景を付けるとよい（このロジックになった意味や作成時に苦労したこと）
読み手の立場になって考える
定数にコメントを付けると理解の助けになる
全体像にあたりを打ってストーリーの目次のような扱いをする
とりあえず書く　WHAT/HOW/WHYでも書こうぜ、いったん雑にコメントを付けて適宜に修正する
TODO: 以外のアノテーションコメントをまとめた – Qiita

6章　コメントは正確で簡素に

さて、先ほどの章で「とりあえず書こうや」と書きましたね。そこを補足する章がこちらの章です。コメントのガイドラインといってもいいでしょう。大事にしたいエッセンスはこれです。

先ほどは概念的な部分の説明がほとんどでしたが、こちらではガイドラインのようなものなのでもっと明確です。それこそ、「こういった場合はこれが良い」ぐらいまで具体的です。

定数にはわかりやすい命名とコメントを書く
実例を書く：処理の結果として入力入れたらこういった処理が返ってくる
明確な言葉を使う：あれ・これ・それなどは厳禁
コードの意図・背景を書く：コードに行きついた経緯や処理を端的に表現
情報密度が高い言葉を使う：一般的に使われている略語を使いましょう
記録すべき自分の情報を書く：コードから絶対読み取れない情報（検討・実装中・エラー）

基本原則としては、5章で書いた「すべてのコメントは読み手のために！」という部分を周到しています。冗長に書くよりも端的に書くほうが好まれます。これはコミットメッセージにも言われることですね。

内容理解が難しい部分として『コードの意図・背景』などがあると思います。ここは、特殊な実装の場合、新規参入したエンジニアが誤ってリファクタをすることを防止することをイメージすると思います。例えば文字列を分割するスクリプトがあった場合、分割のキーとなる文字がなぜそれになったのかというのは決定する場合がほとんどです。なぜそのキーで動くのか？を明確に記しておくことは理解の助けになると思います。

『情報密度が高い言葉』については、例えば奇数を抜き出す処理を「2で割って余りが出る場合Trueを処理する」と書くよりも「奇数を抽出する」と書いてしまったほうがシンプルですよね。奇数なんて微妙な例を出してしまったのですが、エンジニア界隈で使われるアルファベットの文字なんてものが便利だと思います。

メモ

定数にはわかりやすい命名とコメントを書く
実例を書く
処理の結果として入力入れたらこういった処理が返ってくる
明確な言葉を使う
あれ・これ・それなどは厳禁
コードの意図・背景を書く
コードに行きついた経緯や処理を端的に表現
情報密度が高い言葉を使う
一般的に使われている略語を使いましょう
記録すべき自分の情報を書く
コードから絶対読み取れない情報（検討・実装中・エラー）

終わりに

これを台本として輪読会に参加したら「自分の意見と本の意見を明確に分けて書いたほうが良いね」と指摘をもらいました。確かに、自分の言葉で書いてしまうと本の意味を曲解しているように感じてしまいますね。曲解はしている可能性が大いにあるのでツッコミ大歓迎です。許してください。今回は、書き換えるのも大変なのでこのまま出させてもらいま須。もっと良い書き方に関しては模索していきます。というか、輪読会の資料をブログでまとめていくという方針になったのでこれから楽しみです。同僚たちのまとめ方にも注目です。

新しく輪読会のジャンルがサイトに導入されました。これから楽しみにお待ちください！ではでは～