😺

【リーダブルコード】良いコードを書くための原則【入門編】

2021/09/08に公開

Web

メモ

コーディング

idea

「最近プログラミング始めたけど先輩のコードと比べて自分のコードがかなり汚い気がする。
どうやったら先輩のような綺麗なコードを書けるようになるんだろう？」

そんな悩みはありませんか？

だったら、「リーダブルコード」を読みましょう。

この本を読めば、先輩顔負けの良いコードが書けるようになります。

そのくらいの名著です。

この記事では、入門編としてプログラミングの処理についてではなく、表面的な見た目のことについて３つのポイントにまとめて紹介します。

この本の中では、
良いコード　＝　理解しやすいコード
と定義されています。

なので、それを前提にこの記事を読んでいただければと思います。

【見た目上のルール1】名前の付け方にこだわる

まずは、名前の付け方について解説します。

名前を正しくつけることで、読み手により多くの情報を与えることができます。

なので、名前の付け方はとても重要になります。

そして、このセクションでは、名前の付け方のルールを5つ解説します。

1明確な言葉を使う

よりその変数や関数を詳しく表せる単語を使うようにしましょう。

例えば、csvをダウンロードする関数があった場合は、
getCsvよりもdownloadCsvの方が明確だと言えます。

2名前に情報を追加する

名前はコメントのような物です。

なので、伝えたい情報があればそれを名前に詰め込んだ方が良いです。

例えば、
distanceという距離を表す変数には単位を追加して、distance_kmとした方が分かりやすくなります。

3名前の長さを意識する

変数名は長すぎると良くないというのは暗黙の了解となっています。

けれど、今の時代はエディタの補完機能があるので、タイプに時間がかかるというデメリットはないです。

なので、それほど気にしなくてもOK。

どちらかと言うと、無理に短くして情報が上手く伝わらないことの方が問題です。

けれど、名前が長すぎると若干読みづらくはなるので、省略などを活用すると良いです。

documentoはdoc、stringはstrにすると言った感じです。

4名前のフォーマットを活用する

名前のフォーマットで情報を伝えるというのも良い手段です。

例えば、
変数は小文字で書いて、定数は全て大文字で書く
普通の関数は小文字から始めて、コンストラクタ関数は大文字から始める
など。

5誤解されない名前を使う

当たり前ですが、なるべく誤解を生まないような単語を使うことも大事です。

例えば、承認されているかどうかのフラグをapproveという変数名でブール値持っていた場合、
trueの場合に承認されているのかされていないのかがイマイチ分かりづらくなります。

なので、名前をapprovedとした方が誤解を生まなくなります。

【見た目上のルール2】美しさを常に意識する

改行やインデントを駆使して、見た目を整えるというのは意外と大事です。

なぜなら、それだけでもコードの可読性を大きく上げることができるからです。

なので、コードを書くときは、
余白・配置・順序
などにこだわって書く必要があります。

では、もっと具体的にどんなルールを適用すべきかを解説していきます。

1一貫性のある書き方をする

コードを書くときは、一貫性を意識して書くようにしましょう。

例えば、他のファイルでは先に定数を宣言して、その後に変数を宣言するという順序で書いていたとします。

そこで、新たにファイルを作成し、最初に変数を宣言してその後に定数を宣言するという書き方をした場合、恐らく読み手はそのコードを読むときに一瞬戸惑ってしまうでしょう。

また、文字列の宣言時に全て""のリテラルを使っているのに、１箇所だけ''で宣言していたら一貫性が損なわれます。

なので、他のファイルなどや関数などに合わせた書き方を意識するようにしましょう。

2メソッドや変数を上手く使う

変数やメソッドを上手く使って見やすくすることも大事です。

//ダメな例
if(user.signIn && user.authenticate){
  認証が必要な処理
}

//良い例
const isAllowed = user.signIn && user.authenticate
if(isAllowed){
  認証が必要な処理
}

特に共通化できる部分があれば、なるべく共通化した方が良いです。

3縦の線を真っ直ぐにする

これは賛否両論あるかと思いますが、変数宣言などを縦に揃えるテクニックになります。

  const hogehoge = "hogehoge"
  const foo      = "foo"
  const buzz     = "buzz"
  
  const obj = {
    { foo,    hogehoge,    buzz},
    { "foo2", "hogehoge2", "buzz2"}
  }

こんな感じですね。

一々空白を揃えるのが面倒臭いという意見もあるかと思いますが、それ以上に可読性が上がることによるメリットの方が大きいと思うので、僕は賛成派ですね。

4意味のある並びにする

例えば、変数宣言や関数の宣言は

重要順
アルファベット順
使用する順

などに並べた方が分かりやすくなります。

5コードを段落に分ける

関数内などでは、一定の意味を持ったグループごとに段落で分けると可読性がかなり上がります。

例えば、手元にpythonでseleniumを使ってインスタグラムにログインするメソッドがあったので、これを使って解説します。


def login():

  #ページへアクセス
  driver.get('https://www.instagram.com/accounts/login/?source=auth_switcher')
  f = open('insta.txt','a')
  f.write("instagramにアクセスしました\n")
  f.close()

  #メアドと、パスワードを入力
  driver.find_element_by_name('username').send_keys('hogehoge@gmail.com')
  driver.find_element_by_name('password').send_keys('hogehoge')

  #ログインボタンを押す
  driver.find_element_by_class_name('L3NKy').click()
  f = open('insta.txt','a')
  f.write("instagramにログインしました\n")
  f.close()

こんな感じで処理ごとに段落で分けた方が改行しないコードよりも見やすくなります。

【見た目上のルール3】適切なコメントを書く

まず大前提として、コメントの目的をハッキリさせます。

コメントする目的 = 書き手の意図を読み手に伝えること
となります。

これを元に、どんなコメントをするべきかということを解説していきます。

1コメントすべきでないことはコメントしない

確かに、コメントはあった方がコードは読みやすくなります。

しかし、無駄なコメントが多いとそれを読むことに時間が取られるので、結局マイナスになります。

なので、コメントすべきではないことを知ることもかなり大事です。

まず、コメントすべきでないことはコードからすぐわかることです。

//ログインしているか確認する
const isSignedIn = () => {
  ログインしているか確認する処理
}

例えば、このコメントは不要です。なぜなら関数名からその情報が読み取れるから。

また、分かりにくいコードを書いてコメントで誤魔化そうというのもやってはいけないことになります。

その場合はコメント書くのではなく、読みやすいコードにリファクタリングするべきです。

2自分の考えをコメントする

コードから何を、どのようにの部分は大体読み取れます。

なので、なぜそのコードを書いたのかという考えを書く方が大事です。

ただ、もちろんコードを読むのに役立つ情報であればWhatやHowについても書いてもOKです。

3重要事項にコメントをつける

// Todo あとでここに処理を加える

// XXX: このライブラリを暫定的に使っているが、〜という欠陥がある

など

4質問されそうなことを書く

エンジニアは大体全員チームで働いており、人の入れ替わりも結構激しかったりします。

なので、新しい人が入ってきたようにキャッチアップしやすいようにコメントを書いておくというのも大事になります。

例えば、以下のような感じ。

ハマりそうな罠を告知する
このコードを見てビックリしそうなところ、間違えて使う可能性があるところを考えてコメントを書いておく。
全体像をコメントしておく
ファイルごとに「ここのファイルには、APIを叩く時に使う型の一覧が書かれている。」
などと全体像を書いておくと可読性が上がる。
要約コメント
長い関数などには、要はここでは何の処理をしているのかということを要約したコメントを先頭に書いておいた方が分かりやすい。

5良い文章で書く

コメントは確かに大事だが、コメント自体が分かりづらかったら本末転倒になります。

なので、

簡潔に書く
曖昧な代名詞は避ける
正確な情報を記述する
といったことを意識すると良いかと思います。

終わりに

最後まで読んでいただきありがとうございました！

やっぱり、「リーダブルコード」は定期的に見返すと新しい発見や忘れていた大事なことを思い出せたりするので、かなりオススメです。

今回は表面的な見た目などについて書きましたが、次回はもっと具体的な処理の書き方などについて書きたいと思います。

最後に宣伝です。

0からエンジニアになるためのノウハウをブログで発信しています。
https://hinoshin-blog.com/

また、YouTubeでの動画解説も始めました。
YouTubeのvideoIDが不正です

インスタの発信も細々とやっています。

興味がある方は、ぜひリンクをクリックして確認してみてください！

おわり