Murga

個人的に言いたいコト・主張・気持ち。

読みづらいコードを見かけたから文句を言う

読みづらいコードを見かけたから文句を言う。

  1. 変数名が意味を表現していない。
    • 例 : itemNumberdataCount。前者はアイテムの ID かなんかかと思いきや個数 (length) を示すモノ、後者はループ中の index を示す変数名だった。
    • 何が悪いの? : 何のために存在する変数なのか、どんな影響があるのか、いちいち調べて覚えておかないといけなくなる。誤解も生まれやすい。
    • コメント : 名前重要。
  2. 意味に違いのない類語を混在させている。
    • 例 : insideinternal の表現が混在するが同じ意味合いで使っている・使い分けに意図がない。
    • 何が悪いの? : 読み手が表現の違いに理由があるのか調べて判断する手間が出てくる。変数名などで grep する時にモレやすい。
    • コメント : 名前重要。
  3. 全くコメントを書かない。書いてあってもクラス名と同じ文字列が書いてある見出し風のコメント行のみ。
    • 例 : かろうじて見つけたコメントが、設定用の XML ファイルに <!-- HOGE Parameters --> と書いてあるだけ。
    • 何が悪いの? : コードから「Why」が分からない。なぜこのような実装にしたのか、何が狙いかが分からない。すなわち、単に読みづらいコードなのか、何らかの理由でそうせざるを得なかったのか判断が付かず、汚いコードが余計にリファクタリングしづらくなる。
    • コメント : こういう場合は大抵 README も書いていないので、コーディングした本人にロングインタビューしないと解読できない。
  4. 概念的な共通点がないのに共通化する。
    • 例 : 人間とクルマ、両方「走れる」から Runner クラスで共通化だー!みたいな。まぁ英語でいえば rundrive で違うんだけど、それにしたって Runner クラスで共通化する意味が全くない。
    • 何が悪いの? : 本質的に (抽象概念的に) 共通する要素ではないので、子クラスごとに親クラスの実装内容を読み替えないといけなくなる。読み手の脳内バッファが食われて理解に時間がかかる。
    • コメント : 多分、目先のコードを共通化して使い回したいがためだけに、よく考えずにやらかしてる。「共通化」自体が正義だと思い込んでいる。
  5. 早すぎる共通化のせいで共通コードの中に種類別の分岐がある。
    • 例 : 先程の Runner クラスの中に、if 人間なら { … } else if クルマなら { … } みたいなコードがある。
    • 何が悪いの? : 汚いコードが不必要に散在して、リファクタリングが困難になっている。
    • コメント : この時点で「あれ?共通化できてないな?」と思えないということは、抽象概念として捉えられていない。
  6. コードの表面的にも、論理的な構造にも、規則性がない。
    • 例 : 空行の開け方に規則性がない。ディレクトリやファイルの分割単位に規則性がない。
    • 何が悪いの? : 「コレの場合はこう」「アレの場合はこう」と、色々覚えておきながらコードを読む必要があり、読み手の負担になる。
    • コメント : 「場当たり的」などというレベルではない不規則さ。わざと他の部分とは違う書き方をしようとしてるのだろうか。

書いた本人なら改修とかできるのかというと、本人も四苦八苦してる。もう捨てろよそんなコード、ってことで俺が全部書き直した。

「ざっくり」とか言うヤツ、いつまでも「きっちり」できない説

似たようなこと前にも書いたんですけどね…。

neos21.hatenablog.jp

  • ざっくりとですが叩き台を作りました」
  • 「時間ないからざっくり説明するね」

ざっくりしたモノは要らねえ、きっちりしたモン出せや

って思うんだけど、いつまでもきっちしりたモノは出てこない。

大抵は「ざっくりしたモノ」をベースに「ざっくりした別の何か」を作り、それが成果物と呼ばれ始めて、プロジェクト自体がざっくりと終わる。無駄に煩雑で分かりにくくなったメンテ手順やショボいバグの数々は全部運用フェーズに丸投げだ。

時間がないからざっくりしたモノしか作れない、という輩は、ほとんど 100% の確率で、潤沢な時間があったとしても、ざっくりとしたモノしか作れない。要はきっちりしたモノを作るスキルがないのだ。私は能無しだから誰か助けてくれって正直に言わんかい。


一番最初に用意するモノが「ざっくり」していると、それが最初に作られた以上の精度に精密化されることは、まずない。どうしてもそれが「基準」になってしまうからだ。

「本当はこのざっくりとした低品質な叩き台の全てが間違っていると思うんだけど、ゼロから全てを作り直すのは面倒臭いな、俺の責任になっても嫌だし」という、人間誰もが抱きうる逃げの気持ちが生まれるから、最初に作るモノがざっくりしていてはいけないのだ。

「曖昧な表現が飛び交う、ざっくりした要求仕様書」に基づいた開発プロジェクトが成功した試しがあるだろうか?初めに作る資料がざっくりしていなければ、何を作るべきか迷いはないし、万が一抜け漏れがあったとしても、きっちり書かれている中の抜け漏れなので、発見・対策が迅速に行いやすい。

叩き台を作るならざっくり作ってはいけない。きっちり作れ。


個人メモ、勉強した記録を「ざっくり」書いてしまうのは、整理がついていないためだと思う。

自分も、「とりあえずコレで動いたけど、原理を説明しきれないな…」というタイミングはあった。そんな時に書いたメモは「このオプションがないと動かないが何をしているかは分からない」とか、「とりあえずこの行があると上手く動く」なんて書いてあったりする。

でも、こんなメモをそのまま残しても、後で何の役にも立たない。書いてあるのを読み返しても、何も分かりゃしない。

自分の、誰かの役に立つメモにするなら、そんなざっくりした部分があってはいけない。

その日は理解が追いつかなくて曖昧なメモになってしまったら、それはそれで一旦残しておくのは良いが、後で必ず最初からやり直し、同じメモをゼロから書き直すことだ。

同じ内容を入力することになっても、前のメモからのコピペはせず、全てゼロから書き直す。コピペすると「ざっくりした品質」を移植することになるから、コピペは避ける。ゼロから検証をやり直し、メモを書き直すことで、前日よく分かっていなかった部分の理解も追いつき、前日よりはきっちりしたメモになっていることだろう。

きっちりしたモノを作るには、ざっくりしたモノをベースにしてはいけない。

きっちり! 恥ずかしくない! 文章が書ける

きっちり! 恥ずかしくない! 文章が書ける