分野別
📐コード可読性
リーダブルコード, 可読性の話題について扱う.
コーディング規約やスタイルについての一般論をまとめる.
命名規約については別ページに移動 => 📝命名規約概論.
他人野書いたコードを読む話題は, 📝コードリーディング.
commit message の 1 行目の書き方
git - 提言: コミットメッセージの一行目には要求仕様を書け - Qiita
- そのコミットによってプログラムはどんな要件を満たすのかを書く
- メッセージは プログラムを主語とする動詞句 で書く (そして主語はいつもプログラムなので省略します)
Allow log in password longer than 20 characters (20 文字より長いログインパスワードを認める) Recache password database after changing password (パスワード変更後データベースをキャッシュし直す) Animate thumbnail images when they appear (サムネイル画像が現れる時アニメーションさせる) Trim thumbnail images larger than 200x200 px (200x200 px より大きいサムネイル画像を切り落とす)
垂直方向に自動でインデント
【翻訳】私がコーディングで垂直方向にそろえるインデントをとる理由 | POSTD
Emacs だと, M-x align-regexp
Maximul line Length
かつては78文字(Linuxコード規約). 現在は100 or 120が主流.
✅１行の長さ80文字問題と個人的な見解
どうも一般論がよくわからないので推測も兼ねてまとめる.
まずコードとテキストという２つの分類ができる.
コードに関してはコーティング規約があったほうが統一感があってよい. かつてLinuxは80文字だった. これは当時のディスプレイサイズを考慮したもので2020には適切でないとして100charに緩和された.
テキストメールもLinuxにならい80文字, またはさらに少なめの76文字にする慣習が生まれた. これはみやすさのため.
ゲームチェンジャーはWebのCSSによって自動折り返しが登場こと. Webだとレスポンシブに自動で調整することができる. そのため手動で改行しなくてもよくなった.
これからのテキストの折り返しは基本的にエディタなりブラウザなりが自動で折り返しをしてくれることを期待して書くのがよい. もちろんみやすさのための折り返しなのでより見やすいように手動で調整するのはよい.
またコードに関しては規約は必要なため, 80なり100なりのなんらかのルールが必要. 個人的なルールに留めるなら自分がつかっているディスプレイサイズに最適なものがいい.
- refs.
AI Readable code
変数名や関数名は省略表記しない
AI様がわかりにくいような名前はつけない. AIが読んで分かるようにする.
英語に関するTopics
Commit Comment
English Tips
- モデルの名前は名詞にする
- 単数形か複数形か
- 可算名詞か不可算名詞か
- 処理を実行するメソッドは 動詞のみ or 動詞 + 名詞にする
- 二つの単語を繋げてモデルを作る場合は 形容詞 + 名詞 or 名詞 + 名詞にする
English - モデルやメソッドに名前を付けるときは英語の品詞に気をつけよう - Qiita
📐命名規約
プログラミング言語の命名規約. Naming Conventions.
🔖PascalCase
CapitalCase UpperCamelCase PascalCase
- 複合語の先頭が大文字からはじめる.
- camelCaseと区別するために, CapitalCase, UpperCamelCaseと表現されることもある.
🔖camelCase
camelCase, lowerCamelCase.
- 複合語の先頭が小文字からはじめる.
- PascalCaseと区別するために, lowerCamelCaseと表現されることもある.
🔖snake_case
snake_case
- 複合語はすべて小文字
- 単語間の繋がりはアンダーバー _
- Python
🔖kebab-case
kebab-case, lisp-case
- 複合語はすべて小文字
- 単語間の繋がりはハイフン -
- lisp-caseともいう. LISP系言語で採用.
codic
よい変数名を教えてくれるwebサービスcodicクライアント.
- M-x codic: 英語 => 日本語
- M-x codic-translate => 日本語 => 英語(要token)
codic-translateを使うにはtokenを codic-api-tokenに設定する必要がある. 現状は”private/config.el”に書いて読み込んでいる.
Insights
とりあえず書き溜めておく. これをどうするかは後で考える.
✅エディタの置換に習熟すること
可読性をあげるためには, 適切な名前をつける必要がある.
そしてその名前変更は気軽にかつ安全にする必要がある. そうするとエディタの補助は必要不可欠であり, この編集機能に習熟することはとても大事.
💡 Web API設計の命名: snake_case vs camelCase
一般的には snake_case or camelCase.
どうも絶対的な結論はないようにみえる.
誰がどこで使うかという観点で使いやすい方を選ぶ.
💡3つ以上の複合語からなる変数はより大きなデータ構造とそのグループにまとめる
変数名なんて2つの複合語で収まることが多く, それ以上になるなるばより大きな抽象でグループにまとめるべきサインな気がする.
長い変数名は見た目が悪い.
確かに可読性のために丁寧に記述することは大事だ. C言語開発ではやたらとprefixを多用した経験がある. しかし構造体よりももっと簡単に連想配列やその抽象が構築できる令和の現在は,もっとカジュアルにデータをグルーピングしてもいいんじゃないかな？
グルーピングすることで構造がより見いだせるようになり, コードに秩序が加わる.