Pythonコードが増えて迷子になったので、整理アドバイザーGUIを作ることにした
気づいたら、フォルダの中に Python ファイルが増えていた。
そんな経験、ありませんか？
Pythonを書き始めたころ、コードはとても素直でした。
ひとつのファイルに、上から順番に処理を書く。
CSVを読み込む。
少し加工する。
Excelに出力する。
それだけなら、特に迷うことはありません。
ところが、実務で使う処理が増えたり、過去に作ったコードを流用したり、AIに相談してコードを増やしたりしていると、Pythonファイルは驚くほどの勢いで増えていきます。
- CSVを読むコード
- Excel帳票を作るコード
- Access（DB）につなぐコード
- 画像を処理するコード
- 現場ごとに少しずつルールの違う集計コード
AIのおかげで、「動くコード」は以前よりずっと早く手に入るようになりました。
これは、とてもありがたいことです。
以前なら何時間も調べていた処理が、数分で形になることもあります。
でも、その一方で、別の問題も出てきます。
動くコードは増えた。
でも、どこに何があるのかわからない。
どの処理がどこから使われているのかわからない。
似たような関数が別のファイルにもある。
昔作った便利処理を、どこに置いたか忘れてしまう。
最初は便利だったはずのコードたちが、いつの間にか「どこに何があるかわからない森」になっていきます。
どこかに道はあるはずなのに、木々が多すぎて見えない。
そんな状態です。
修正しようと思ったら、同じようなコピペ処理が3か所にある。
どのファイルが入口で、どのファイルが部品なのかわからない。
消していいファイルなのか、まだどこかで使っているファイルなのかわからない。
こうなると、コードを書く時間よりも、コードを探して迷子になっている時間のほうが長くなってしまいます。
🗺️ コード整理に必要なのは、気合いではなく「地図」
コードが増えて迷子になったとき、最初にやりたくなるのは整理です。
ファイル名を変える。
フォルダを分ける。
似た処理をまとめる。
共通化する。
クラスにする。
どれも大事な作業です。
でも、いきなり整理しようとすると、かなり危険です。
なぜなら、今のコードがどうつながっているのかを把握しないまま動かすと、思わぬところで壊れることがあるからです。
実務コードでは特にそうです。
- CSVの行数が変わってしまう
- Excel帳票の列がずれてしまう
- 集計結果の合計値が微妙に変わる
- AccessやDBとの連携部分で想定外のエラーが出る
見た目には少しきれいになったように見えても、出力される結果が変わってしまえば実務では使えません。
だから、コード整理で最初に必要なのは、気合いではありません。
まず必要なのは「地図」です。
どこに何があるのか。
どのファイルが何をしているのか。
どの処理がCSVを読んでいるのか。
どの処理がExcelを出力しているのか。
どこにパスや設定値が直接書かれているのか。
これらを見えるようにしてから、少しずつ整理していく。
そのために、この連載では小さなGUIツールを作っていきます。
名前は、Pythonコード整理Advisor GUI。
この連載では、親しみを込めて 「整理Advisor」 と呼ぶことにします。
🤖 整理Advisorは、勝手にコードを書き換えない
整理Advisorは、いきなりあなたのコードを書き換えるツールではありません。
勝手にリファクタリングするものでもありません。
勝手にフォルダを移動するものでもありません。
勝手にファイル名を変えるものでもありません。
まずやることは、観測です。
今あるPythonファイルを読み、そこに何が書かれているのかを見えるようにします。
- どのファイルにimportが多いのか
- どのファイルに関数が多いのか
- どのファイルにクラスがあるのか
- CSV処理、Excel処理、DB連携、画像処理のどれに近いのか
- ハードコードされたパスや設定値がないか
そうした情報を、GUI上で確認できるようにします。
この連載で大事にするのは、次の4つのサイクルです。
- 【観測】 コードを読み、まず現在地を知る
- 【助言】 処理の特徴から、配置や命名の候補を出す
- 【地図】 ファイルや処理の関係を記録する
- 【安全】 整理前後の結果を比較し、壊れていないことを確認する
実務コードは、きれいに書き直すためだけに整理するのではありません。
壊さず、見える化し、次に直せる形へ育てるために整理します。
この考え方を、整理Advisorという小さなGUIツールを作りながら身につけていきます。
💻 この連載で育てていく4つのGUI画面
整理Advisorは、最終的に4つのタブを持つ構成へ育てていく予定です。
1. コード解析タブ
まずは、Pythonファイルを読み込んで、その中にどんな要素があるのかを表示します。
たとえば、次のような情報です。
- import一覧
- 関数一覧
- クラス一覧
- よく使われている処理
- ハードコード候補
- ファイルの行数
- コメント行の目安
最初から完璧な解析は目指しません。
まずは、ファイルを選ぶ。
中身を読む。
気になる単語や命令を数える。
それを画面に表示する。
このくらいの素朴なところから始めます。
いきなり難しいことをする必要はありません。
まずは、自分のコードを「外から眺める」ための画面を作ることが大事です。
2. Advisor診断タブ
次に、読み取った情報をもとに、そのスクリプトがどんな種類の処理なのかを判定していきます。
たとえば、CSVをよく読んでいるならCSV処理系。
Excelに出力しているなら帳票系。
AccessやDBにつないでいるならDB連携系。
画像ファイルを扱っているなら画像処理系。
そうした特徴を見ながら、整理Advisorが次のような提案を出します。
- このファイルはCSV処理系かもしれません
data_processingフォルダに置くとよさそうです- 設定値をYAMLに分けられそうです
- クラス名はこのようにすると役割が伝わりやすそうです
- このファイルは少し大きくなっているので分割候補です
もちろん、Advisorの提案が絶対に正しいわけではありません。
最終判断は人間がします。
整理Advisorの役割は、答えを押しつけることではなく、判断材料を並べることです。
3. プロジェクト地図タブ
ファイル単体を見ているだけでは、プロジェクト全体の形は見えません。
そこで、プロジェクト地図タブでは、ファイル同士の関係や役割を記録できるようにしていきます。
たとえば、次のような情報です。
- どのファイルが入口なのか
- どのファイルが共通処理なのか
- どのファイルが設定を読むのか
- どのファイルがCSVを出力するのか
- どの処理がどの順番で動くのか
最終的には、こうした情報をYAMLファイルとして記録できるようにします。
たとえば、project_map.yaml には、ファイルの役割や配置場所を書きます。pipeline.yaml には、処理の流れを書きます。
コードだけを見て思い出すのではなく、プロジェクトの地図として残しておく。
これができると、数か月後に自分で見返したときにも、かなり助かります。
未来の自分に対する引き継ぎ資料にもなります。
4. リファクタリング安全確認タブ
コードを整理するとき、一番怖いのは「動いているように見えるけれど、結果が変わっている」ことです。
特に、実務で使うCSVやExcel帳票では、少しのズレが大きな問題になります。
行数が変わっていないか。
列数が変わっていないか。
主要キーの件数が変わっていないか。
金額や数量や回数などの合計値が変わっていないか。
こうした確認を、整理前と整理後で比較できるようにします。
リファクタリング安全確認タブでは、整理前の出力ファイルと整理後の出力ファイルを選び、差分を確認します。
たとえば、CSV同士を比較する。
Excel同士を比較する。
行数、列数、列名、主要キー、数値合計を比べる。
そして、問題がなければ、
安全に移行できそうです
と表示する。
差分があれば、
置き換える前に確認してください
と表示する。
整理Advisorは、コードをきれいにするためだけの道具ではありません。
実務コードを壊さずに育てるための道具です。
📈 整理Advisorの全体イメージ
この連載で作っていく流れを、簡単に図にすると次のようになります。
[対象Pythonファイル]
↓
( 観測 ) ──> コード解析タブ
↓
( 助言 ) ──> Advisor診断タブ
↓
( 地図 ) ──> プロジェクト地図タブ（YAML記録）
↓
( 安全 ) ──> リファクタリング安全確認タブ
↓
[壊さず整理された、未来へ続くPythonプロジェクト]
最初から、ここまで全部を作るわけではありません。
いきなり完成形を目指すと、ツール作り自体が迷子になります。
だから、少しずつ作ります。
まずは、Pythonファイルを選ぶだけ。
次に、画面に中身を表示する。
その次に、ファイル内の特徴を数える。
少しずつ、処理の種類を判定する。
さらに、置き場所や名前の候補を出す。
やがて、プロジェクトの地図を作る。
最後に、整理前後の出力を比較して、安全に移行できるか確認する。
このように、小さく作って、小さく育てます。
🔍 最初は素朴な方法でいい
コードを読む方法にも、いろいろあります。
でも、この連載では最初から難しい方法を使いません。
まずは、文字列検索や簡単な判定で、Pythonファイルの特徴を拾っていきます。
たとえば、ファイルの中に read_csv という文字があれば、CSVを読んでいそうだと考える。to_excel という文字があれば、Excelに出力していそうだと考える。connect や cursor という文字があれば、DBと関係していそうだと考える。
もちろん、この方法は完璧ではありません。
コメントアウトされた処理まで拾ってしまうかもしれません。
文字列の中に書かれた説明文まで、本物の命令として数えてしまうかもしれません。
似た名前の関数を、同じものとして扱ってしまうかもしれません。
でも、最初から完璧である必要はありません。
まずは素朴に作ってみる。
動かしてみる。
そこで見えてきた限界に合わせて、道具を一段ずつ増やしていく。
この連載では、その順番を大切にします。
あれ？
このやり方だと、実務のコードを解析するときにちょっと危ないぞ……
そんな壁に実際にぶつかったところで、コードをより正確に読むための強力な切り札を登場させます。
最初から正解を知っている前提で進むのではなく、作りながら困り、困ったところで設計を一段上げていく。
整理Advisor自身も、少しずつ設計を学んでいくわけです。
📦 クラス設計は、「役割に名前をつけること」
この連載のもうひとつのテーマは、クラス設計です。
クラスというと、少し難しく感じるかもしれません。
でも、最初はこう考えるとわかりやすくなります。
クラスは、役割に名前をつける道具です。
- ファイルを選ぶ役
- ファイルを読む役
- コードの特徴を数える役
- 診断結果を作る役
- 画面に表示する役
- 安全確認をする役
こうした役割が1つの場所に混ざりすぎると、コードはまた迷子になります。
だから、整理Advisorを作りながら、処理の役割を少しずつ分けていきます。
最初は1つのファイルで作ってもかまいません。
でも、処理が増えてきたら、
これは画面の仕事だろうか？
これは分析の仕事だろうか？
これは診断の仕事だろうか？
これは設定として外に出したほうがよいだろうか？
と考えていきます。
この問いかけこそが、クラス設計の入口です。
🚀 この連載で目指すもの
この連載で目指すのは、ただ便利なGUIツールを作ることだけではありません。
自分のPythonコードを、少し離れたところから観察できるようになること。
処理の役割を分けて考えられるようになること。
どこを共通化し、どこを設定として外に出すか判断できるようになること。
そして、実務コードを壊さずに育てられるようになること。
これが目標です。
AIによって、コードを書く速度は大きく上がりました。
だからこそ、これから大事になるのは、増えすぎたコードをどう整理するかです。
動くコードを増やすだけではなく、あとから読める形にする。
自分だけでなく、未来の自分にも伝わる形にする。
壊さず、見える化し、次に直せる形へ育てる。
いきなり完璧な設計を目指す必要はありません。
最初は、Pythonファイルを選んで画面に表示するだけで十分です。
そこから一歩ずつ、読み取り、分類し、助言し、地図を作り、安全に整理できる形へ育てていきます。
一緒に、少しずつ道を切り開いていきましょう。
次回は、tkinter を使って、Pythonファイルを選んで画面に表示する小さなGUIの入口を作ります。
📅 Part 1：まず動くAnalyzerを作る編のロードマップ
- 第1話： 迷子になったPythonコードに地図を作る構想（今回）
- 第2話： tkinterでPythonファイルを選ぶGUIを作る
- 第3話： 文字列検索でimport・def・classを拾ってみる
- 第4話： read_csvやto_excelなど、処理の特徴を数えてみる
- 第5話： コメントアウトまで命令として数えてしまったので、コードの読み方を一段上げる
- 第6話： Pythonコードをより正確に読む方法へ進み、スクリプトを分類する
