ログイン

こんな「コメント」はうれしい!〜読みやすいコードの話〜

 2021.2.16 イクメンゴリラー福田 ゴリラーブログ ブログ

 

 

イクメン(おむつ替え)ゴリラーの福田です!

 

突然ですがみなさん、「優れたコード」とはどんなコードだと思いますか?

 

ITエンジニアの定番書となっている「リーダブルコード」には、

「他の人が最短時間で理解できるコード」と定義されています。

 

サービスの開発やメンテナンスをしていて、「コードを書いた人を呼びだしたい!」と

なる時が多々ありますが、履歴を見ると、それが過去の自分だったりするから驚きですね!

 

「コードは、書かれる時間より読まれる時間の方が10倍長い」という名言がありますが、

実際に業務をしていて、それは大袈裟ではないと思います。

 

つまり、「理解しやすいコードを書く」ということは、「早くコードを書く」より

何倍も全体工数への影響が大きいということですね。

 

「優れたコード」を書くための方法として、先ほど紹介した「リーダブルコード」には、

以下のような具体例がまとめられています。

 

インデントの数や、コードの縦の列を揃える。

処理のまとまりごとに、段落に分ける。

変数名やメソッド名では、具体的で意味や目的が明確に伝わる命名をする。

というような、「見た目」を整える方法をはじめ、

 

条件式では、できる限り肯定型の条件を先に書く。

ネストを深くしない(条件式をいくつも組み合わせない)。

一つのメソッドには、一つの役割のみ行わせる。

というような、コードをガッツリ変更する方法まで、

「リーダブルコード」には様々な実践例が記載されています。

 

しかし、上記のような方法は慣れが必要な部分もあり、

いきなり効果を発揮するにはハードルが高いかなと思います。

 

そこで私がオススメするのは、「コメントの書き方を工夫する」という方法です。

 

こんなコメントがあると嬉しい!

 

そこで「リーダブルコード」の内容も参考に、私イクメンが

「こんなコメントはありがたい」と思うものを紹介したいと思います。

 

①処理の要約

メソッドの冒頭などに、処理のまとまりについての説明があると、

理解のスピードが各段に上がって嬉しいですね!

 

コメント例

 // 〇〇をベースに△△を取得

// サブクエリを先に作る

$works_query・・・

 

 

②なぜ(他の方法でなく)このコードを選択したのか

コードを読んでいると「なぜこの方法を選択したのだろう」

「修正した方がいいのかな」と悩むことがあります。

 

でも、それは既に検討されていて、あえて別の方法を選択している場合が多いんですよね。

コメントを通してそれが分かると、不要な改善をしなくて済んで嬉しいですね!

 

コメント例

 // 〇〇が期待通りに動かないため、再取得

 

 

③「マジックナンバー」の説明

コードを読んでいると、突然謎の数字(マジックナンバーと言われます)が

使われていることがあります。

いったい何の数字か分からず、理解に時間がかかってしまいます。

そこで、何かしら必要があって数字を使う時は、その説明があると嬉しいですね!

 

コメント例

 // 区分 1:朝, 2:昼, 3:夜・・・

 

 

④想定される問題

将来的に改善した方がいいと思うことを書いておくと、「今はあえて実装は控えたのだな」と

安心してコードを読み進めることができ、理解のスピードが上がります!

 

 

思いつく限り例をあげてみましたが、それ以外にもコードを読む人が疑問に思いそうなことを

積極的にコメントとして残しておくといいのかなと思います。

 

以上、私イクメンが思う「うれしいコメント」でした。

 

みんなで、「優れたコード」を書けるエンジニアを目指していきましょう!

 

 

© 2021 Mountain Gorilla Co., Ltd. 

プライバシーポリシー

%d人のブロガーが「いいね」をつけました。