異業界転職 ~転職後に振り返ったらポートフォリオにスペルミスが160箇所あった件~
こんにちは
PortalKeyのしゃりです。
前回の記事では、未経験時に作ったコードの設計上の反省点を書きました。
今回は誤字(= typo)の検出つまりは開発環境側のお話をします。
誰に向けて書いたの?
- 転職とかおいといて、とりあえずプログラミングを始めてみた方
- 他業界からITエンジニア(特にWeb業界)を目指して個人開発中の方
- プログラミングに手を出してみたいが、誤字が怖くて尻込みしている方
はじめに
突然ですが、初学者の皆さんはプログラミングで誤字ったらどうなると思いますか?
数年前までの私には「誤字ったらエラーで死ぬ」というイメージがありました。それ故に自分なんかがプログラムを完成させられるわけがないと決めつけてプログラミングを敬遠していました。
でも、実は死なないんですよね。何故かというと、「書いた時点で不整合を教えてくれる機能がエディターにデフォルトであるから」です。
しかし、それで誤字の全てが解決するわけではありませんでした。
「宣言時の誤字」=「自分が名付けした時の誤字」はプログラム的にはエラーではないので検出されません。
const numbre = 0 // 宣言時の誤字は検出されない
console.log(nubemr) // 使用時の誤字(=宣言されていない変数)はコンパイルエラーになる
とはいえ、人間にとっては読みにくいですよね。良くないことです。
実際に、実務で指摘を受けました。
以下、レビューで実際にいただいたコメントから抜粋
(誤字を)もうちょっと自分で何とかしてみましょう
レビューで本質的でないこと…(中略)…を指摘されるのはレビュイーにとってもレビュワーにとっても勿体ないです
これに対して、部分的な解決策となる誤字検出の自動ツールを入れてみました。
ESLintとPrettierの設定よりも考慮することが少なく、数段簡単だったので初心者にもオススメできます。
どんな誤字を見落としていたのか
具体的には、currentIdをcurrenrIdと書くようなスペルミスだったり、大文字小文字のルール違反を見落としていました。(セルフレビューを通り抜けていました)
Tips: 大文字小文字のルール
Goではprivateなものを、Reactでは変数や通常の関数をローワーキャメルで、
記述する文化があり、弊社もそれに習っています。
cultural area | UpperCamelCase | lowerCamelCase |
---|---|---|
Go | Publicなもの | privateなもの |
React | ReactComponent | function, variable, constant |
Goの命名: (公式)Effective Go
Reactの命名:(公式の和訳)React/React用語集/コンポーネント
他にも命名の大切さと一般的に推奨される命名の考え方がリーダブルコードに書いてあるので読みましょう。(積読への自戒)
誤字の何が悪いのか
誤字は単に「間違いだから」、「読みにくいから」という理由だけで悪いのではありませんでした。
- 読みにくい = レビュワーの負担が増える
- 意図しない解釈をされると、バグの温床になる(保守性が悪い)
スペルミスで別の単語と勘違いさせるだけでなく、スペルは合っていても大文字小文字で意味合いが変わるので機能を勘違いさせる(上述のGoの命名、Reactの命名のリンクを参照ください) -
1行1行に責任を持てていない
誤字以外の見落としもある可能性が高い
参考: HatenaBlog なぜtypo(スペルミス)がいけないのか?
リンク
> レビュアーの負担が増える
参考: Qiita スペルミスの多いコードを持つプロジェクトにありがちなこと
リンク
> - (セルフではない)レビューに頼っている
> 他人にコードの妥当性の判断を丸投げするような人間が良いコードを書けるわけもなく
> - 締め切りギリギリ、もしくはオーバーでそれをする余裕がない
> - スペルミスへの意識が低い、英語が苦手
> - プロジェクト後期やメンテナンスフェーズでひどい目に合う(主に書いた当人以外が)ので、仲間を大事にしない人間だと思われてしまう。
Code Spell Checker
誤字の原因として自分の場合は以下2つが当てはまっていると思いました。
- 時間的な余裕がない
設計も書くのも「遅い」ためコーディングもセルフレビューも焦って作業している - 1行1行に責任を持っていない(レビューに頼っている)
心構えの問題(?)
この課題に対しては「頑張る」「沢山練習して上達する」と言ってしまいそうですが、それでは改善にならないので具体策を探した結果、Code Spell Checkerに辿り着きました。
インストール
Code Spell Checker(VSCode Marketplace)でInstallを押したらインストール完了です。
インストールした瞬間からcurrenr
のような存在しない単語がlintエラーのように検出されました。
(なんと、VSCodeのGUIでコミットする場合はそのコミットメッセージも誤字チェックされます)
しかしこのままでは社名やライブラリ名等の独特な単語もエラー扱いで検出されます。
ホワイトリスト
そこで、キーワードのホワイトリストへの登録で対応しました。
"cSpell.userWords": ["tailwind","envrc","godotenv","gorm","vtuber","vtubers"]
全体設定とリポジトリ毎の設定
さらに、個人開発ではコメントを多用しており、ほとんど日本語な上に、ホワイトリスト登録するまでもないような1度しか登場しない英単語も使っています。また、インフラ関係では一見意味のない定型の文字列を使うこともあります。
そこまで検出するのは逆効果だと思い例外を設定しました。
参考: 【VS Code】cSpell でスペルチェックの例外を設定する方法
この時、次の3点の理由から設定ファイルを分けました。
- 上述の通り、個人開発にだけ適用したい例外があった
- 社内プロダクトではコメント部は例外にしたくなかった
- Code Spell Checkerの社内導入はしないため、社内プロダクトでは.vscodeファイルをgitignoreしていないため、そこに書き込むことが不自然であった
↓このファイルは書き込んだリポジトリにだけ適用されます。
コメントや文字列部と定型文を例外に登録しました。
なお、from ".*"
は意図的に登録しませんでした。import文でディレクトリやファイル名のスペルミスの誤字に気付けるためです。
"cSpell.ignoreRegExpList": [
"/arn:aws:*.+/g",
"`.*`",
"'.*'",
"\".*\"",
"// .*",
"-- .*",
"{/\\*.*\\*/}",
"<!-- .* -->"
]
↓このファイルは自分のVSCodeで開いている全てのファイルに適用されます。
全角英数字、平仮名カタカナ漢字を例外に登録しました。
"cSpell.ignoreRegExpList": [
"[0-9A-Za-zぁ-んァ-ヶ亜-熙纊-黑]+",
]
Tips: `\"`, `.*`, `\\*`って何?
正規表現で、.*
が「任意の文字を任意の数」、\*
は文字列の*
を意味します。
正規表現 メタ文字一覧の.
, *
の覧をご参考ください。
\
は¥
と同じ扱いです。エスケープ処理と言い、直後の記号(メタ文字)の効果を打ち消して文字列として扱うようにしてくれます。
※正規化とは似て非なる単語なので注意
- jsonのエスケープ
jsonでも\
をエスケープとして扱います。
そのためこの設定ファイル内では/
1本ではjsonのエスケープと解釈されるため、正規表現のエスケープをするためには2本必要になります。
(あまり自信が無いです。詳しい方がいたら補足していただけると幸いです。)
余談:Discordで顔文字等が壊れる場合もエスケープ処理が使える?
これは正規表現ではなくMarkdownのお話ですが、
(; ・`д・´)(; ・`д・´)
(*_*)
↑こう書くと `で挟まれた部分がコードブロック↓になり、*で挟まれた部分は強調されます。
(; ・д・´)(; ・
д・´)
(_)
(; ・\`д・´)(; ・\`д・´)
(\*_\*)
↑こう書けば↓のように期待通りになります。
(; ・`д・´)(; ・`д・´)
(*_*)
ちなみに、すでに見つかっている誤字に対しては右クリックのみでホワイトリスト登録や修正することができます。
(しかも昇順になるように挿入してくれるようです)
また、登録した単語数が増えるほど管理が難しくなっていくので、dictionary機能も使っていきたいと思っています。
CLIで全ファイルチェック
VSCodeは開いているファイルを中心に検閲してくれるだけで、全ファイルはチェックしてくれないような挙動をします。(lintチェックもそんな感じですよね)
しかし、今回の様に途中でチェックツールを導入した際にはひとまず全ファイルをチェックしたいものです。
そこでCSpell CLIを使いリポジトリ内を一括でチェックしました。
npm install -g cspell@latest
なお、CLIでcspellを叩いた際には上述のsetting.jsonが適用されません。
rootに以下を追加します。
(この非DRYな設定はこの初回にしか使わないためokとしました。チェック後はcommitせずに消しました。)
{
"$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
"version": "0.2",
"userWords": [上述のsetting.jsonと同じ],
"ignoreRegExpList": [上述のsetting.jsonと同じ],
"ignorePaths": ["node_modules",".next","LICENSE","go.sum","go.mod", 他、チェックが不要なファイル名]
}
個人開発のリポジトリのrootで一括チェックしました。
> cspell "**"
> ...略...
> CSpell: Files checked: 144, Issues found: 169 in 38 files.
ポートフォリオにスペルミスが160件
ようやく、タイトル回収です。
上述の通りホワイトリスト登録等をしたうえで、今も開発を続けている個人開発のソースコードの自分がコーディングしたファイル全てを開いたところ、160件以上の誤字が検出されました。
(CLIの方が若干多いのが気になりますが。)
転職後の開発中も見つけるたびに修正してたつもりなのですが…。
これに関しては、タスクのスコープを広げ過ぎない範囲で修正していくつもりです。
社内導入は難しい…?
自分だけこのツールを入れたことへの問題点は、自分にだけ誤字が検出されることです。
誰かのプルリクに誤字が混ざっていた場合、自分の手元ではエラーとして出続けます。それが自分のタスクのスコープを明らかに外れていた場合、直してしまうのも微妙な気持ちになります。
なので、会社には既存の誤字を全て修正する許可を取りました。ただ、今後も誤字を見つけるたびにそうできるわけではないので、諦めるべきか迷い中です。
では社内全員に使ってもらうべき…?
今は微妙かなと思います。全体的なコストに対し、おそらく現状の弊社ではまだメリットが小さいのです。
(スタートアップのシードステージで開発人員3人)
また、社内導入には以下の3つの方法を調べる必要があると思います。
-
cspell.json
とsetting.json
に分けずにDRYにする
CIを回すためにもCode Spell Checkerがcspell.json
を読み込んでほしい。 - VSCode以外の開発者でも同じ使用感で使えるツールを探す
弊社にはvimユーザーがいます。 - user設定である
/Users/ 略 /Roaming/Code/User/settings.json
を無視する設定にする
会社側はコメント欄も誤字チェックしたいのに、ユーザー側でコメント欄を無視していたら意味がありません。
弊社も無事に規模が大きくなれば導入するかもしれません。
おわりに
誤字について調べる中で自分には今動けば良い、レビューに任せれば良いという感覚があるのだと自覚しました。
typoの本質はそこであり、自動検知は表面的でしかも部分的な解決にしかならないのでしょう。
それでも、自動化で生まれた余裕から、本質的な部分の改善へ使える時間を増やせるはずだと思います。
また、実務では外部ツールも当たり前に使っていますが、未経験者にとっては導入もカスタマイズも難しかったりします。その点、Code Spell Checkerはインストールボタンを押すだけで誤字を検出してくれ、ホワイトリスト登録も簡単なので初心者にも非常に易しいと思います。
※複数個所にまたがる命名変更はVSCodeのF12
の機能を使うと簡単に直せます。
なお、本記事はAIにもレビューしてもらいました。ファイルが少ない時はこういう手もありますね。それでも何回も聞き直さなければ全部の誤字を洗い出してはくれなかったですが。
以上、今回は誤字と表面的な解決策について書きました。
本質的な部分での具体的な取り組み方も模索していきます。
最後までお読みいただきありがとうございました。
良ければいいねフォローお願いします!
Discussion