84:リポジトリのルートディレクトリはシンプルに構成する

プログラミング迷子: リポジトリルートにファイルがたくさんありすぎる

  • 後輩W：先輩、引き継いだプロジェクトのリポジトリなんですけど、ルートディレクトリにファイルがありすぎて何から手をつけて良いかわからないんです。

  • 先輩T：READMEファイルはある？　あればそこに説明が書いてあるんじゃない？

  • 後輩W：READMEにはファイルの説明は書いてなくて、sshの秘密鍵の作り方と、Vagrant 1 とDocker 2 のインストール方法が書いてありました。

  • 先輩T：まじか……。それで、ルートディレクトリにはどんなファイルとディレクトリがあるの？

リポジトリのルートディレクトリは油断すると多くのファイルが置かれてしまいます。 特に最近では、多くのツールやサービスがリポジトリのルートディレクトリにある特定のファイル名で動作を設定できるようになっているため、ルートディレクトリは何でも置き場になってしまう傾向があります。

1

https://www.vagrantup.com/

2

https://www.docker.com/

具体的な失敗

リポジトリルートに以下のようなファイルやディレクトリがあると、それぞれの用途を短時間で把握するのは難しいでしょう。

.circleci/            config/                     manage.py
CHANGELOG.md          deploy.md                   package-lock.json
Makefile              deployment/                 package.json
Pipfile               docker/                     pull_request_template.md
Pipfile.lock          docker-compose.local.yml    static/
README.md             docker-compose.yml          templates/
Vagrantfile           file/                       test.md
accounts/             front/                      tests/
api/                  help/                       tox.ini
batch/                issue_template.md
changelog/            log/

このリポジトリルートは、いろいろな目的のファイルが全部入り状態になってしまっているため、扱いにくい状態です。 この状態でファイル構成の説明をREADMEに書いても、焼け石に水です。 一度このような状態になってしまうと変更の影響範囲が予想できないため、構造の整理整頓に手間がかかります。

cover

（中略）詳細は書籍 自走プログラマー をご参照ください

ベストプラクティス

リポジトリのルートディレクトリには、リポジトリの主目的に合った、見た人に注目してほしいファイルやディレクトリだけを置きましょう。 たとえば、リポジトリの主目的がPyPIに公開するPythonのパッケージであれば、 README と LICENSE の他に、パッケージングに必須となる setup.py や pyproject.toml などの設定ファイルを置くのが一般的です。 こういったファイルがルートディレクトリにあれば、リポジトリを見た人はREADMEを詳しく読まなくてもリポジトリの目的を把握できます。

リスト 4.1 重要度に応じて誘導するように整理しましょう
.circleci/      Makefile       changelog/     doc/
.github/        README.md      deployment/    docker/
CHANGELOG.md    Vagrantfile    djangoapp/     vueapp/

cover

（中略）詳細は書籍 自走プログラマー をご参照ください