f:id:ShotaNukumizu_1000:20220102090648p:plain

おはようございます。Shotaです。

今回の記事では、悪いコードを書かないようにするために大事なことについて話していきます。

「悪いコード」の定義は人それぞれだと思いますが、本記事では「自分以外の誰かが読んでもひと目で理解しにくいコード」と定義します。悪いコードを書かないようにするために特別なことをする必要はありません。

今回の記事を確認して、自分が普段書いているコードの状態を再確認できれば非常に幸いです。

コードは誰が読むのかわかりません。プロジェクトを離れた後、不具合や仕様の変更があれば引き継いだ人がそのコードを読みます。その人が簡単に理解できるコードを書くことは非常に重要です。

それでは早速、本題に入りましょう。

悪いコードを書かないようにするためのポイント
まとめ
参考サイト

悪いコードを書かないようにするためのポイント

①：適切な名前をつける

コードを書く際に使う変数や定数に適当な名前をつけてはいけません。より適切な名前をつけましょう。

以下のコードは、買った商品の値段の合計を集計するプログラムです。

x_list = {
    'orange': 100,
    'banana': 150,
    'milk': 200
}

y_list = list(x_list.values())
print(f'total: {sum(y_list)}')

上記のコードは読みづらいです。適切な名前が思いつかない場合、どうしても定数にx_listのようなわかりにくい名前をつけがちです。

名前が曖昧だとその変数や関数が保つ役割がわからないので、そのメソッドの処理をきちんと確認するという無駄な時間を使うことになります。

読みやすいコードを書くためには、変数や定数、関数には適切な名前をつけましょう。

ちなみに上記のプログラムを改良すると以下のようになります。

goods = {
    'orange': 100,
    'banana': 150,
    'milk': 200
}

prices = list(goods.values())
print(f'total: {sum(prices)}')

これで多少は見やすいコードに仕上がりました。

②：本当に必要なコメントを書く

意味のないコメントは避けましょう。せっかくコードをきれいに書いても、コメントだらけのコードは読みづらくなってしまいます。

特に、

自分のやりたいことが書かれていないコメント
処理の仕組みを説明しているコメント

は良くありません。処理の結果が正しいかどうか判断できないためです。コードを書いた人がどのように考えて処理を作ったのか理解できれば、

ロジックが間違っているか？
やりたいことが違うか？

これらを判断できます。処理を作成した意図を簡潔にコメントに残すようにしましょう。

他にもプロジェクト内でコメントのルールを定めることで、より読みやすいコードに仕上がります。

③：コードを「段落」に区切る

文章は複数の段落に分割されています。それは、

似ている考えをグループにまとめて、他の考えと分けるため
視覚的な「踏石」を提供できる。これがなければ、ページの中で自分の場所を見失ってしまう
段落単位で理解できるようにするため

これと同じような理由で、コードも「段落」に分けて考えるべきです。例えば、以下のようなひとかたまりのコードは読みづらいです。

# ユーザのメールアドレスとパスワードを送信して、新しい友達のユーザを友達リストに追加する
class User:
    def __init__(self, name, email, email_password, *friends):
        self.name = name
        self.email = email
        self.email_password = email_password
        self.friends = friends
    def show(self):
        return f'Name: {self.name}, Email:{self.email}'
    def get_friends(self):
        return list(self.friends)
    def create_friend(self, new_friend):
        post_data = {'email': self.email, 'email_password': self.email_password}
        form_valid(post_data)
        if form_valid():
            self.friends.append(new_friend)
        else:
            FormError('The form is not valid.')

わかりにくいので、このクラスを以下のように分割する。

class User:
    # ユーザの基本的なステータスを定義
    def __init__(self, name, email, email_password, *friends):
        self.name = name
        self.email = email
        self.email_password = email_password
        self.friends = friends

    # ユーザのステータスを表示
    def show(self):
        return f'Name: {self.name}, Email:{self.email}'

    # ユーザが友達になっているユーザをリスト化して表示
    def get_friends(self):
        return list(self.friends)

    # ユーザの友達を新規作成する
    def create_friend(self, new_friend):
        post_data = {'email': self.email, 'email_password': self.email_password}
        form_valid(post_data)

        # 入力されたフォームが有効であれば友だち追加、そうでなければエラーを出力
        if form_valid():
            self.friends.append(new_friend)
        else:
            FormError('The form is not valid.')

このようにして段落ごとにコードを分け、それに加えてコメントを追加すると見やすいコードに仕上がるのだ。

コードも文章と同様に、「段落」を作ることが非常に大事である。