他の人のコードが読みづらい理由

Question

コメントがあっても、他の人のコードが読みづらい理由を
①コードを読んだことも書いたことのない人向け
②コードが読める人向け
の二通りで教えてください。

私は
①については、
人の字が読みづらいように、コードにも癖が出る
と答えます。
②については、
いろいろ理由があって整理できていません。

Answer 1

概論

数学の証明や、合奏の楽譜を読むにはそれなりの基盤が必要です。
どちらも構成要素は単純です。
論文なら、数式だし、楽譜なら音符です。
個々の構成要素を理解できるだけでは、全体の理解 はできません。
字面から 頭の中にイメージを構築 することが必要だからです。
( 全く専門外の分野の専門書の場合、日本語でかかれていても読み通せないのも同じです。
その場合は、専門用語の意味がわからないことも大きな理由ですが、結局は、頭に中にイメージをつくることができないからです。)

プログラムコードの場合は、
メモリー中(変数) が時間の経過によってどう変化するか？
処理しようとしている問題をどの様に変数にマップして、変数間にどんな関係を持たせているのか？
を頭の中に構築することが必要です。

質問への回答

他の人のコードが読みづらい理由についての回答ですが、
①コードを読んだことも書いたことのない人向け
個々の要素 (予約語、イディオム)に不慣れな為に、問題解決の様子を頭にイメージを構築できないからです。

②コードが読める人向け

• 個々の要素 (予約語、イディオム)の理解ができるとしても、
  コードが対象としている問題そのものに不慣れで、問題解決の様子を頭にイメージを構築するのに時間がかかるからです。

• あるいは、そこで用いれている解決手法に不慣れで、問題解決の様子を頭にイメージを構築できないからです。
  例:
  再帰的な手法を知らない人は、再帰的な解決法のコードは理解できないでしょう。
  Rails を理優したコードでは、多くの暗黙の決まりを知らなければ、理解はできません。
  ruby のコードを読み書きるだけでは、読んでいるコードが、全体の中でどんな位置・役割を
  果たしているかがわからないはじなので。

• そもそも扱っている問題 あるいは解決手法が複雑過ぎて、頭にイメージを構築できない場合もあります。
  読む側が予想している解法と全く異なるアプローチで解かれている場合などです。

ケーススタディ：

• JavaScriptで渦巻き上に数字を並べたい https://teratail.com/questions/20868

には、いろいろなコードが回答として上がっています。

コードを読んだことも書いたことのない人は、理解することは相当困難と思います。

コードをある程度読める人でも
質問文をよまず、、プログラム中のコメント (もともとコメントはほとんど無いですが)をカットして、
コードだけを提示されたら、なにをしていいるかを想像するのは困難でしょう。
質問文が提示されたら、大分 敷居は低くなりますが, 回答文にある手法の説明などがなければ実感がかかかります。
手法の説明を頭においてコードをみながらその手法をなぞるのと、
コードだけから手法のイメージを構築するのは、困難度、掛かる時間に大きな差がでます。

この問題を自分で解いたことがあり 読もうとしているコードがその時の類似の手法をつかっているなら、すぐに理解できるでしょう。
コードでつかわれて居る手法が、未経験、異質のもの場合でも解くべき問題のモデルやその声質は頭にイメージできているので、解法の意図を理解はしやすくなります。

Answer 2

ある人Aが，ある人Bに「どこそこへ行くように」と指示する例えが分かりやすいのでは？
(1)同じゴールに辿り着くためにも，行き方はたくさんある．（アルゴリズムの違い）
(2)指示の仕方には，歩く距離と方角のほか，特徴で記述する人もいるでしょう．（手続き型や関数型・論理型など使用言語の違いによるものなど）
(3)細かく自分で指定する人もいれば，他人の作った地図を使っておおまかに説明する人もいる．（言語の抽象度や使用ライブラリの違いなど）
(4)使う特徴や単位は説明する人事に異なる場合がある．（変数の使い方や名前の付け方など）

同じ目的を達成するにも，これだけ手段は異なる．
コメントではコードが達成するべき目的を書くかと思いますが，手段まで書く人はあまりいない．
手段がわからない場合他人のコードはわかりにくいし，目的も手段もわからない場合はもっとわかりにくい．
そういうことだろうと私は思っています．
（ ）内の説明は①の人に対してはせず，②の人に向けて話せばいいと思います．

Comments

[manman]

（1）と（4）の問題くらいしか考えていませんでした。

Answer 3

ご質問を私なりに解釈してみました。

①コードを読んだことも書いたことのない人向け
既にあるソースを解析するのに何故時間がかかるのか、①の人に説明する場面ですね？

②コードが読める人向け
コードを読める人は「既にあるソースを解析するのに何故時間がかかるのか」既に理解しているので、改めて説明する必要はないでしょう。たぶん、どんなコードが読みにくいのか？ですね？

この前提でざっと回答してみます。

①コードを読んだことも書いたことのない人向け

バズルのように難解なコードもあれば、丁寧に解説された読みやすいコードもあります。
パズルのように難解なコードですとパズルを解くのと同じ苦労がありますので時間がかかります。
丁寧に解説された読みやすいコードでも、数100ページ理解しようとすると数学の参考書数冊分を理解するような苦労があります。

②どんなコードが読みにくいか？

• インデントがむちゃくちゃなコードは脳が理解することを拒否します。

• 無闇にgotoしているコード（最近、見ることはないですが）

• 変数名や関数名が妥当でないコード（例えばPowerOnOff。IsPowerOnなら誤解の余地がないです)

• コメントが古いままのコード

• コメントがそもそもないコード

• 一塊の処理を細かく分割しすぎているコード（例えば数10行の処理を数行×10個へ分割等）

• 極端に長い関数

• 自分が知らないテクニックが使われているコード

勉強不足です。ゴメンナサイ。

• 高度なテクニックが使われているコード

読めないのは事実ですが、適切な使い方を否定するものではありません。
例えば下記です。
C++のテンプレート・メタ・プログラム
Cの超高度なプリプロセッサ・プログラム
boostと言うOSSライブラリはこれらの宝庫です。

Answer 4

コードを読んだことも書いたことのない人

が、コードとコメントを見て、理解できる状況が存在することから、コメントが相当丁寧に書いてある状況を想像しますが、
そもそも、コメントを書く方針には、
0. 全てのコードにコメントを書く
0. 必要なところだけ書く(ほぼ書かない)
があると思います。

前者の場合は、

コードを読んだことも書いたことのない人向け

• コメントだけでは筋が通っていない(コードにしか存在しないけれど、重要な部分がある)
• コードの説明に終始してコードがやりたいことが理解できない書き方をしている

のどちらかだと思います。

コードが読める人向け

• コードが何をしたいかわからない。
• 直観に反した(「自分だったらこう書く」という物と違う)動きをしていて、動きが把握しづらい
• データ変更と描画が同時に行われているなど、多数の状況を把握し続ける必要がある

というのがあるかなと思います。

後者の場合は、

コードを読んだことも書いたことのない人向け

読むことは不可能です。
可能性があるとしたら、関数を順に呼び出すだけでロジックが無い関数(呼び出している関数名がコメントの役割になっている)ぐらいだと思います。

コードが読める人向け

• コメントの内容が難しい(読み手の知らない専門用語があるなど)
• コメントが日本語としておかしい
• 関数の粒度が大きい
• 想定外の解法
• 何をやっているか見た目でわからない
• 汚くて読む気がしないのに、読む必要がある(読むのが遅くなる)
• ネストが深かったりやインデントが出来ていないなど、見た目が悪い
• 読む人が知らない、暗黙の了解がある
• 関数の切り出し方がおかしく、呼び出し元の関数の動きを把握しないと読めない

などでしょうか・・
最後の理由はかなり色々あると思いますが
大抵は、汚くて読めないか、ロジックが理解できないかだと思います。
ただ、そういう場合はコメントがあってもなくても理解度は変わらない気もします。

僕がコメントを書く必要があると感じるのは

想定外の解法
何をやっているか見た目でわからない

の時だと思っているので。それ以外はコードの汚さに起因する問題でコメントで解決できるものではないと思います。

Answer 5

①コードを読んだことも書いたことのない人向け

この人はそもそもチュートリアル的なコードにそれ以上の分量の説明文がついていないとコードを読んで理解することはできないのではないでしょうか？
英語で書かれた相対性理論の論文を読むようなもので
英語も分からなければ、論文とはどういう構成で書かれているものかも知らず、更にはその論文を読むための数学的物理的な知識も無いとなれば、幾ら論文が読みやすく書かれていても…。

②コードが読める人向け
コメントがあっても、他の人のコードが読みづらい理由

プログラムそのものが読み易いかどうかに関しては次の要因によって変わってくると思います。

1. 読みやすいように意識して書かれているかどうか？
2. 仕様書や設計書がきっちりしているかどうか？
3. コードや関連資料が一定のルールに従って書かれているか、読解者がそのルールを知っているか？
4. プログラムが実行している内容を読解者が理解しているか？

2,3に関しては複数人で開発するプロジェクトならコーディングルールや文書作成ルールがあるはずです。
自社のルールに従って正しく作成されたコードや資料は、他人が読んだってそれが同じ会社のエンジニアなら読みづらいということは比較的少ないと思います。

4に関しては、透視投影変換の関数コードを見ても、行列のフィルタを利用して値を変更している事が分かっても、3D関連知識がなければ結局それが何なのか分かりません。
読んだ人はその関数が何をしているのか理解できたとは言えないと思います。
コメントに関数概要が一行程度書かれていても、プログラム言語に精通していてもこれは変わりません。

これらが全て満たされていれば特別読みにくいという事も無さそうに思います。
どれかが欠けているのでは無いでしょうか？

Answer 6

こんにちは。
＞他の人のコードが読みづらい理由...
とありますが、「他の方がかかれているにもかかわらず読みやすいコード」を考えてから逆説的に読みづらい理由を考えたほうがアプローチしやすいように思いました。

①コードを読んだことも書いたことのない人向け
コード自体が不要なくらい、日本語で懇切丁寧にコメントがあれば、プログラミング知識がない方でも自明に理解できるはずです。

②コードが読める人向け

• 記法が自分と同じないし標準的。変数名やクラス名のCamel記法・ハンガリアン記法...、インデントのつけかた、中括弧の位置など。
• 意味がわかる変数名やクラス名などである。
• DRY、YAGNI、KISSの原則を理解し、沿っている。
• メソッドが単機能。
• コメントに、全条件に関して記述されている。文字列検索であれば、見つからなかった場合や、検索文字（引数）自体が空文字だった場合の戻り値も言及してある。インデックスや位置については、0からはじまるのか1からはじまるのかなども記載されている。
• べらんめえ調の投げやりコメントがない（見ると萎えます）

Answer 7

1番は他のコメントでだいたい尽くされていますので、2番目だけ答えます。

コンソールプログラムとかちょっとしたスクリプトみたいに1ファイル内で実行して終わり、というものなら別ですが、多くのプログラムは複数のファイルが連携して動いています。

その過程で、「この処理がどこから呼ばれるか or どこを呼び出すか」がわからなくなってしまう場面がしばしば生じます。

1. 抽象クラスやダックタイピングで、実際に呼ぶクラスがはっきりしない or 変化する
2. メタプログラミング経由で呼び出しているので、直接の呼び出しが見つからない（Railsではよく発生します）
3. フレームワーク側から呼び出すので、その挙動を把握していないと「いつ、どういう状況で」呼ばれるのかわからない（巨大なフレームワークではよくあります）

1つ1つのコードはパズルの1ピースみたいなもので、全貌がわからなければどういう意味を持っているのかわからない、という場面も多々存在します。

Answer 8

①コードを読んだことも書いたことのない人向け

圧倒的にボキャブラリと経験が足りない

②コードが読める人向け

右利き、左利きみたいなもの
左利きの人が鋏を巧く使えないみたいな(鋏には右利き用、左利き用があります)