コードを本に例えてみる

はじめに

本の構成と良いコードに共通点があるのではと思ったので、思いつたことを雑多にまとめます。
なおここで言う本は小説ではなく技術書などのイメージです。

目次の場合

本の目次を見てみると、部、章、節あたりが記載されています。
これをコードに置き換えると、
部：パッケージやある内容のまとまり
章：ファイルやClass
節：Interface（publicメソッド）
のようにイメージできるかと思います。

このように考えた場合、節（関数名）はその章（Class）の個々の内容（機能）が記載されていることがわかります。
逆に言うと、関係の無い内容が登場しないことが当然だと理解できます。
その部（package）に関係の無い章が記載されることもないはずです。

読みづらいコードの例

目次で考えた場合、読みづらいコードは前述したとおり部（package）や章（Class）に関係の無い章（Class）や節（Interface）が含まれている、関係はあるがタイトルから内容が理解できない、といったケースがあるかと思います。
本の場合、別の章の内容であるべきものを記載することはないでしょう。
またタイトルから推測できないなら目次からは内容を推測できず、全部内容を見に行く必要があります。
全く嘘の内容になっているとなると、誤解してしまう恐れもあります。

• 悪い例

- 1部
    - 1章
        - 1.1節 aaaについて
        - 2.1節 ZZZについて
        - 1.1.3項 aaaのbbbはccc
        - 節 temp

class 1章 {
    public 1.1節 aaaについて() {
    }
    public 2.1節 ZZZについて() {
    }
    public 1.1.3節 aaaのbbbはccc() {
    }
    public 節 temp() {
    }
}

• 良い例

- 1部
    - 1章
        - 1.1節 aaaについて
        - 1.2節 cccについて
    - 2章
        - 2.1節 ZZZについて

class 1章 {
    public 1.1節 aaaについて() {
    }
    public 1.2節 cccについて() {
    }
    private 1.1.3節 aaaのbbbはccc() {
    }
}

各章の場合

各章にはその内容に紐づいた節と更に項があります。
前述したとおり、節をInterfaceとした場合、項はprivateメソッドになってきます。
節はその内容が長くなる場合は大体項に分かれてくる、逆にあまり長くない内容なら項に分けずに記載されているかと思います。
これをコードで考えると、publicメソッド（節）内で直に処理を書かず、各粒度ごとに関数（項）に分割し、この分割した関数をpublicメソッドが呼び出すイメージです。
逆に内容が多くない（項に分けるほどでもない）場合は処理がそのまま記載されることになります。

class 1章 {
    public 1.1節() {
        1.1.1項()
        1.1.2項()
        1.1.3項()
    }
    public 1.2節() {
        1.2.1項()
    }
    public 1.3節() {
        aaaについて
        bbbだから
        cccである
    }
    
    private 1.1.1項() {
    }
    private 1.1.2項() {
    }
    ……
}

読みづらいコードの例

よくある読みづらい、変更しづらいコードの場合、public関数内で大量の処理がべた書きされているものがあります。
それを本で考えると、内容が項に分割されず節の粒度で全内容（処理）が記載されているイメージになります。
区切りなく書かれていると、全体をざっくり把握したくとも全て読む必要があり、理解できないことはないものの読みにくさを感じるかと思います。
欲しい情報をピンポイントで探そうにも、全て読んでいく必要があり大変です。
また途中に内容（処理）を足したくなった場合、前後の文章（処理）がおかしくならないように足す必要もでてくるので、表現が難しくなるかもしれません。

• 項目が分割されていない場合

# 1章
## 1.1節
aaaの内容は～～（1.1.1の内容がそのまま記載）～～である。  
bbbの内容は～～（1.1.2の内容がそのまま記載）～～である。
ccc～～～

class 1章 {
    public 1.1節() {
        ～～～
        aaaは～
        ～～～
        ～～～
        bbbは～
        ～～～
        ～～～
        cccは～
        ～～～
    }
    ……
}

• 項目が分割されている場合

# 1章
## 1.1節
### 1.1.1項 aaaについて
### 1.1.2項 bbbについて
### 1.1.3項 cccについて

## 1.2節

class 1章 {
    public 1.1節() {
        1.1.1項 aaaについて()
        1.1.2項 bbbについて()
        1.1.3項 cccについて()
    }
    
    private 1.1.1項 aaaについて() {
    }
    private 1.1.2項 bbbについて() {
    }
    private 1.1.3項 cccについて() {
    }
    ……
}

さいごに

読みにくいコードを書く人になんと言えば理解してもらえるだろうかと悩んでいる際に思いつたことを簡単にまとめてみました。
また本では例えきれない部分も多々あるかとは思います。
今回は章をClassとして見ましたが、章をpackageとして考えることもできるかと思うので、今回のものはあくまで一例です。