こんにちは！
先日「リーダブルコード」というIT界隈で有名な書籍を読みました。
プログラミングにおいて「リーダブルコード」とは、他の開発者や未来の自分などが理解しやすいコードを書くことを指します。これにより、コードの保守性が向上し、バグの発見と修正が容易になります。
本記事では、プログラミング初学者の私がこれから始まるチーム開発で個人的に意識しようと決めたリーダブルコードの内容を3つ紹介します！
最初に結論
- 適切なコメントを適度に書く
- 説明変数をつける
- 誤解されない名前をつける
順番に行きます！
1. 適切なコメントを適度に書く
コードからすぐにわかることをコメントに書かない
コメントの目的は、書き手の意図を読み手に知らせることです。また、コードの補足説明をするためのものであり、コードそのものが何をしているかを明確にする役割があります。
しかし、コメントは何でもかんでも残せばいいと言うものではありません。
以下全てに当てはまるコメントは不要と言えます。
- コード自体が十分に明瞭
- コードにはない新しい情報を提供するわけではない
- 読み手がコードを理解しやすくなるわけでもない
悪い例:
# ユーザーの年齢が18歳以上か確認する
if $user.age >= 18;
このコメントは、コードが何をしているかをそのまま繰り返しているだけで、追加の情報を提供していません。コメントがなくてもコードの意味が十分に明確であるため、このようなコメントは不要と言えます。
良い例:
# ユーザーが成人しているか確認する
if $user.age >= 18;
このコメントは、コードの意図を明確にしており、処理がなぜ行われているのかを説明しています。コードを読む人が、この条件が何を意味するのかを理解しやすくしています。
コメントは短い文章で適切に
コメントは簡潔かつ明瞭であるべきです。長文のコメントは読むのが大変で、かえって読み手の理解を妨げることがあります。
悪い例:
# この部分のコードはユーザーが正しくログインしているかを確認し、不正なアクセスを防ぐために使用されます。ここでチェックされていないと、未認証ユーザーが不正にアクセスできる可能性があります。
if $user.is_authenticated;
冗長な説明は読み手に負担をかけ、コードの理解を妨げることがあります。
良い例:
# ユーザーがログインしているか確認
if $user.is_authenticated;
2. 説明変数をつける
説明変数とは
説明変数とは、コードの一部を説明するために用いる変数のことです。これにより、コードが何をしているのか一目でわかるようになります。
悪い例:
str = "123suzuki456";
x = str.substring(4,10);
xという名前では、変数の内容や役割が全くわかりません。
良い例:
str = "123suzuki456";
username = str.substring(4,10);
ここでは、str.substring(4,10)の部分がusernameという変数に代入されています。この例では、strの部分の文字列を取り出してusernameとしていることが明確になります。
説明変数を使用することで、コードの意図が明確になり、後から見たときにも理解しやすくなります。
3. 誤解されない名前をつける
抽象的な名前よりも具体的な名前を使用する
具体的な名前は、コードを読んだ時にすぐにその役割が理解できるため有用です。例えば、strという名前よりも、usernameやuserIDといった具体的な名前の方が適切です。
悪い例:
$data = get_username_from_email(email);
dataという名前では、返されるものが何か明確ではないです。
良い例:
$username = get_username_from_email(email);
usernameという名前は、関数が何を返すのかを明確に示しています。
他の意味と間違えられることはないだろうか？と自問自答する
変数や関数の名前は、コードの理解を助けるために非常に重要となります。誤解を招く名前を避けるために、命名には特に注意を払います。
例えば、dataやtempといった一般的すぎる名前は避け、何を表しているのかが明確な名前を選びます。また、名前が他の意味と混同されないか確認することも重要です。
悪い例:
$tax_price = calculate_price(items);
tax_priceという名前では、計算結果が「税込」なのか「税抜き」なのか、はたまた別の税金関係の値なのか、さまざまな解釈ができ、読み手に誤解を与える可能性があります。
良い例:
$price_including_tax = calculate_price(items);
計算結果が「税込価格」というように、何を示しているのかを読み手に明確に伝えています。
まとめ
リーダブルコードを意識することで、他の開発者や自分自身などが後でコードを読み返した際の理解が容易になります。
適切なコメントを残し、説明変数を活用し、誤解されない名前を選ぶことで、読みやすいコードに近づくと思います。また、これらを意識することで、コードの保守性と品質が向上し、プロジェクト全体の効率向上にもつながると思います。
僕は今回記事にした内容を守って開発に取り組み、エンジニアとしてのレベルを上げていきます！この記事をご覧方になった方も、少しでもこの記事で学びになったことがあれば嬉しいです！
最後までご覧いただき、ありがとうございました！