読みやすいコードを書くために気をつけていること

業務でコードレビューを受けたり、コードレビューをしたりする機会が増えてきたので、
個人的に読みやすく綺麗なコードを書くために気をつけていることをまとめたいと思います。
また、最近はTypeScript/React.jsでフロントエンド開発がメインのため、
サンプルコードはそちらを使用したいと思います。

読みやすいコード/綺麗なコードとは

読みやすいコード、綺麗なコードの解釈には個人差があると思いますが、
ざっくり下記項目ができていたらオッケーとします。

変数名、関数名が適切な名前になっていること
プロジェクトの命名規則に統一されていること
改行が適切に行われていること
ネストが深すぎないこと
不要なコメントがないこと/コメントが適切に残されていること
処理の共通化が行われていること

では、1つずつまとめていきます。

変数名、関数名が適切な名前になっていること

まずは、変数名、関数名が適切な名前になっていることについてですが、
変数名と関数名の2つに分けてまとめていきたいと思います。

変数名

booleanの変数名
例：サイドバーを開くか開かないかの条件判定

const [isSidebarOpen, setIsSidebarOpen] = useState<boolean>(true);

booleanを判定する命名としてはis~~と記述してあげることで、
その変数名はtrueなのかfalseなのか直感的にわかるようになります。
また表示するかしないかの判定にはshow~~と命名することで、
直感的にわかりやすくなりおすすめです。

関数名

フロントの開発では特になのですが、入力フォームのonChangeやonBlur等の
イベントハンドラーを実装することがあるかと思います。
各イベントのハンドラーが直感的にわかる関数名として、
下記サンプルになります。

  const onChangeInputHandler = useCallback((e: ChangeEvent<HTMLInputElement>): void => {
    // change処理
  }, []);

  const onBlurInputHanlder = useCallback((e: FocusEvent<HTMLInputElement>): void => {
    // blur処理
  }, []);

  const onSubmitFormHandler = useCallback((e: FormEvent<HTMLFormElement> | undefined) => {
    // submit処理
  }, []);

上記のサンプルコードの各ハンドラーではどのような処理が行われるか関数名を見ただけで、
イメージができるようになっていると思います。(なっていなかったらすみません。。。)

変数名/関数名まとめ

変数名と関数名に共通して言えることは、パッと見ただけでどのような値を持っている変数なのか、
どのような関数で、どのような処理を行っているのかが、ソースを1行1行目を凝らして見なくても
わかる命名になっていることが重要ということです。

プロジェクトの命名規則に統一されていること

これは言うまでもないとは思うのですが、変数名や関数、ファイル名の命名がプロジェクトで
統一されていることが一番大切です。
開発者それぞれが、バラバラの命名を行っている場合には、コードレビューをするコストも上がりますし、
何よりメンテナンスする際に、処理を追うのが大変になります。
なので、プロジェクトで決められた命名規則に沿って開発を行うことが、今後の開発やメンテナンスの
コストを下げることができるので、とても重要です。
ただし、現在の命名規則より良いものがある場合等は、プロジェクトのリーダー等に提案するという
行動は積極的に行っていくべきだと考えています。

改行が適切に行われていること

例としては下記の3点になります。

1行が長すぎる問題
HTML要素の改行問題

具体的に説明をしていきたいと思います。

1行が長すぎる問題

これはコードレビューをするまたはしてもらう際の問題点になります。

上記ピクチャの48行目に着目してください。
ここでは、1行の記述が長いため自動的に改行がされてしまっています。
この自動的な改行があるとソースコードを読むのが一気に大変になります。
またエディターで2分割して開いた場合に横スクロールをしないと
ソースの全体が見えないようになってしまいます。
なので、下記ピクチャのように適宜改行を入れることが重要です。

HTML要素の改行問題

この問題は好みが分かれるかもしれないのですが、inputやbutton等の
要素に適宜、改行を入れないととてもソースコードが汚く感じます。
例：改行がバラバラ

      <TextField name="password" type="password" fullWidth label="パスワード" margin="normal"
        variant="outlined" onBlur={onBlurInputHanlder} onChange={onChangeInputHandler}
        value={values.password} error={Boolean(touched.password && errors.password)}
        helperText={touched.password && errors.password} />

例：改行の統一

      <TextField
        name="password"
        type="password"
        fullWidth
        label="パスワード"
        margin="normal"
        variant="outlined"
        onBlur={onBlurInputHanlder}
        onChange={onChangeInputHandler}
        value={values.password}
        error={Boolean(touched.password && errors.password)}
        helperText={touched.password && errors.password}
      />

上記の例は大袈裟かもしれないですが、明らかに改行が統一されている方が
綺麗にかつ読みやすいコードになっていると思います。

改行が適切に行われていることまとめ

改行問題で紹介したことは、フロントエンドであればESLintの導入を行えば防げるので、
フロントエンド開発を行う上ではESLintの導入は必須であると思います。

次回

少々、記事が長くなってしまったので、今回説明しきれなかった下記は次回にしたいと思います。

ネストが深すぎないこと
不要なコメントがないこと/コメントが適切に残されていること
処理の共通化が行われていること

ryubloblog’s diary

宮城県の仙台で働くプログラマーです。