これは何?
ここのところきれいなコードの重要性についての議論がtwitterで活発にされていると思います。
私は過剰にきれいにする必要はない場合もあると思いますが，最低限は読めるコードを書くべきだという考えなので，自分がやっている最低限わかりやすいコードを書くための工夫を紹介いたします。
この記事のスコープ
- 基本的なコードを書く際のお作法的な部分を書こうと思っています。
- デザインパターンや設計レベルの話はしません。
- ひろゆき氏の批判をするのが目的ではなく，自分の意見を書くのでコメント等での誹謗中傷はお控えあそばせ
1. 変数名を読みやすいものにする
hogeやfugaは自分もちょっと機能を試す時には使うことはありますが，基本的に変数を見て何をやっているのかわからないものはNGだと思います。
最低限気をつけることは以下です。
- 変数は英語でなるべく適切な英語を使う: 生成AIや類語辞書，OSSを参考にする
- 変数に単位があるならば単位をつける e.g. time_s，time_ms
- 変数が長くなる場合には単語ごとに区切る(後述するコーディング規約に従って切ると良い) e.g. port_scanner，ScanClass
- 環境変数，定数は大文字にする(コーディングルールを優先するでよい)
さらにレベルアップしたい方は品詞に気をつけるとさらに良いです。
変数名を省略しつつ，可読性を確保する
いろいろな情報を変数名に入れると変数が長くなりすぎてしまうことがあります。
そういった際には適切な省略をすると良いです。
略し方を検索できるサイトを参考にしてもいいかもしれませんが略し方の主要な方針は以下になります。
- 前置詞だけを残す e.g. convert_to_string→to_string
- ingを省略する
- 母音を削る e.g. image→img
- 強い音を残す e.g. server→svr
略した結果わかりづらくなると本末転倒なので，略しても意味がわかるか確認してください。
より良い変数名のために
フィルテルソンによるより良い変数名のための3ステップモデルを紹介しておきます。
- 名前に含めるべき概念の選択: コメントを書くくらいなら変数名にその単語を入れる。
- どんな単語を使うか: 各概念を表す同義語に注意する。
- どう組み合わせるか: 自然言語としても自然な語順になるように単語を並べる。
2. 関数を使う
適切に関数を使うことで処理の流れがわかりやすくなります。
個人的には関数を使うかどうかは以下を基準に判断しています。
- 同じ処理を繰り返しているか
- 1つの処理の塊が5行以上になるか
処理の塊はスクロールが必要ないくらいの単位に分割する。
3. 適切なコメントを書く
- 関数を使う際には関数で実施する処理の概略を書いておく
- そのコードがなぜ必用なのか作成者の意図を書く
4. コーディング規約に従う
プログラミング言語ごとに定められているコーディング規約に沿ってコードを書くことでコードの一貫性を保つことができます。
コーディングルールに従うため
- formatter
- linter
を導入するとコーディングルールの適用が楽になります。
pythonの場合には
参考になるリンク集