GitHubアップローダのファイル構造について考えてみた

アカウント登録CUI対話を、どこに追加するか。

ファイル構成

これまで

• ./GitHubUploader/
  • database/
  • web/
  • uploader/
  • GitHubUploader.py

以下のコマンドで実行する。

python3 GitHubUploader.py `pwd`

案1

• ./GitHubUploader/
  • database/
  • account/
  • web/
  • uploader/

少ない変更と影響で済む。

しかし、以下の違いがあるのに同一階層のためわかりにくい。

ディレクトリ	内容	位置づけ
database	アプリ機能を実現するためのデータベース作成処理。	アプリ固有
web	アプリ機能を実現するためのWeb処理。HTTP通信やGitHubAPIクライアント。	汎用ライブラリ（アプリで使う機能のみ）
account	アプリ機能を実現するためのGitHubアカウント管理CUI対話。	サブ-コマンド
uploader	アプリ機能の実装。	メイン-コマンド

使われ方としては以下のような包含関係になる。

• uploader
  • account
    • web
      • database

上記のような木構造にできない理由は以下。

• webやdatabaseはアプリ機能の下地。各所で使うため、特定の機能の配下に置くことができない（重複するから）
• webに関してはGitHubAPIクライアントとして独立できるかもしれない。しかし、アプリ機能で使う分しか実装しておらず機能不足

仕方なく同一階層にしているが、そのせいで違いがわからない状態になっている。

案2

• ./GitHubUploader/
  • database/
    • init/
    • account/
  • web/
  • uploader/

DBを操作するのがメインなのだから、database配下にするという考え。

でもそれだったら、uploaderもdatabase配下にすべき。また、アプリ機能がDBの下というのがおかしい。

案3

• ./GitHubUploader/
  • database/
  • web/
  • uploader/
    • sub/
      • account/
    • main/
      • repo/
      • issue/
      • aggregate/

mainとsubの分離が無駄に見える。

案4

• ./GitHubUploader/
  • database/
  • web/
  • upload/
  • sub_command/
    • account/

sub_commandが無駄に見える。database, webはメインではないしコマンドでもない。

案5

• ./GitHubUploader/
  • database/
  • web/
  • command/
    • account/
    • upload/

GitHubアップローダの機能はすべてcommand/に入れる。するとuploader/でなくupload/が相応しいか。

では、コマンドではないdatabaseやwebとは何なのか。という疑問を持ってしまう。

案6

• ./GitHubUploader/
  • lib/
    • database/
    • web/
  • command/
    • account/
    • upload/

ディレクトリ	説明
lib	Pythonコード上からだけ呼び出せるコードの実装
command	CUIなどユーザが呼び出せるコードの実装

ふつうlibといったら.lib, .dll, .soなどのバイナリファイルを連想する。しかも汎用性のあるもの。しかし実際はアプリ機能の一部である。はたしてlibのイメージに沿っているのか。

utilならいいかもしれないが、曖昧すぎて意味不明。

案7

• ./GitHubUploader/
  • private/
    • database/
    • web/
  • public/
    • account/
    • upload/

語がわかりにくい

CUIなどユーザから見えるインタフェースを持っているか否かで二分している。

分類としては間違っていない。databaseやwebはユーザから見えない。PythonまたはSQLite3で呼び出すインタフェースしか持っていない。対してaccountとuploaderはCUIインタフェースを持っている。

しかし、private, publicという語がわかりにくい。「誰からみて」なのかが明記されていないからか。「ユーザから見て」private,publicと言っているつもり。

ところで、このソースコードは開発者しか見ないはず。開発者からみればすべてpublicである。開発者しか見ないコードの分類なのに、なぜユーザ視点を用いるのか謎。だからこの分類の意味がわかりにくいのか。

理由はある。最初からコードを追うなら、まずユーザインタフェースから読み始める。ユーザインタフェースのコードがどれだか分かる分類がされていれば、最初に読むコーが見つけやすくなる。

ただ、publicとprivateの語でそれと認識できるかは疑問。だからといって他にピンとくる語が思いつかない。

文脈で分ける

ユーザが触れるインタフェース部分の文脈やプロトコルの層で分類するのがいいのかもしれない。

• database
  • SQLite3
    • (DB作成コード)
• web
  • HTTP
    • 1.1
      • (HTTP通信処理コード)
  • service
    • GitHubAPI
      • v3
        • (GitHubAPI仕様実装コード)
• execute
  • Python3
    • (Pythonで実行できる処理の実装コード)
• UI
  • CUI(コンソール, ターミナル, 標準入出力, shell)
    • (CUIから呼び出される処理の実装コード)
  • GUI
    • ウィジェット・ツールキット
      • X11
      • GTK+
      • KDE
      • Qt
      • Tk
      • wxWidgets
    • HTMLレンダリングエンジン
      • Trident
      • Gecko
      • KHTML

案8

案7を規模にあわせて縮小すると以下。

• ./GitHubUploader/
  • database/
  • web/
  • cui/
    • account/
    • uploader/
    • GitHubUploader.py

省略できるものは以下。

• DBシステムはSQLite3のみなので省略
• 実行するプログラミング言語はPython3のみなので省略
• ネットワーク通信プロトコルはライブラリでカプセル化されるので省略
• ユーザインタフェースはCUIのみなのでGUI,UIは省略

案9

UIの拡張に備えておく。CUIだけの予定だが、あとでパッケージ名の変更がないように事前に決めておく。

• ./GitHubUploader/
  • database/
  • web/
  • ui/
    • cui/
      • account/
      • uploader/
      • GitHubUploader.py
    • gui/

略称	フルネーム	説明
CUI	Character User Interface	文字だけで操作する。
GUI	Graphical User Interface	アイコンとマウスで操作する。
NUI	Natural User Interface	タッチパネルや音声入力など人間が自然にできる動作で操作する。

ずいぶんと曖昧なネーミングと分類。その曖昧さが分類の崩壊をまねくのだが大別としては十分か。

名前はどれがいいか悩ましい。

• ui/c/, ui/g/, ui/n/
• ui/cui/, ui/gui/, ui/nui/
• ui/character/, ui/graphical, ui/natural

もしくは案8のように以下でもいいか？それぞれ文脈が違うので間違ってはいない。

• database/, web/, cui/, gui/, nui/

サブコマンド

サブコマンドについて考えてみた。サブコマンドは基本的にDB操作のためのCUIツールのこととする。たとえばアカウント登録CUI。追加するなら以下の3つがありうるか。

サブコマンド	説明
account	アップローダで使うGitHubアカウントを登録するCUI対話
other-repo	他者のGitHubリポジトリURLからリポジトリ情報を取得するCUI対話（ライセンス表記自動化の下地）
license	指定したキーがGitHubライセンスに存在するか問い合わせるCUI対話（ライセンス表記自動化の下地）

GitHubアップローダとしては、account登録機能さえあれば満足できそう。残り2つは実装できるかどうかも、すべきかどうかもわからない。それよりもっとすべきことが多い。「リポジトリのアップロード」という範囲を超えた機能なので対象外か。

他のDBはサブコマンド不要と思われる。

DB	不要な理由
api	初回にマスターDBを作るだけで十分。変更があったら根本的に作りなおすことになる。Accept:〜previewなどの小規模変更について追従する方法があってもいいかもしれないが。
language	初回にマスターDBを作るだけで十分。
repo	初回の一括作成と、アップローダによる追加、削除、編集で足りる。
GnuLicense	そもそもこのDBは必要ですらない。あくまでライセンスの説明や選択を助けるオマケ情報。

所感

とりあえず案8を採用するか。