動くけど読みにくいPythonコード、そのままで大丈夫？現役SEが教える整理のポイント

Pythonでプログラムを作っていると、

「とりあえず動いたから完成」

と思って、そのまま使い続けることがあります。

特に、ChatGPTなどの生成AIを使ってコードを追加していると、短期間で機能を増やせる一方で、少しずつコードが長くなり、どこに何が書いてあるのか分かりにくくなることがあります。

最初は問題なく動いていても、後から修正しようとしたときに、

「どこを直せばよいのか分からない」

「少し変更しただけなのに、別の機能が動かなくなった」

「同じような処理が何か所にも書かれている」

「自分で作ったコードなのに、久しぶりに見たら内容を思い出せない」

という状態になってしまうこともあります。

今回は、現役SEである私が、Pythonコードを整理するときに確認しているポイントを紹介します。

1．長すぎる処理を分ける

1つの関数や処理の中に、たくさんの役割が詰め込まれていると、コードの流れを理解しにくくなります。

例えば、1つの処理の中で、

・ファイルを読み込む

・データを加工する

・データベースへ保存する

・画面に結果を表示する

といった処理をすべて行っている場合です。

最初は1か所にまとまっているため分かりやすく感じますが、コードが長くなるほど、どの部分が何を担当しているのか見つけにくくなります。

このような場合は、処理ごとに関数を分けます。

例えば、

・ファイルを読み込む関数

・データを加工する関数

・データを保存する関数

・結果を表示する関数

というように役割を分けると、コードを読みやすくなります。

また、エラーが発生した場合も、どの処理に問題があるのかを特定しやすくなります。

2．同じ処理を何度も書かない

コードを追加していると、似たような処理をコピーして使うことがあります。

しかし、同じ処理が何か所にも書かれていると、修正が必要になったときに、すべての場所を変更しなければなりません。

1か所だけ修正を忘れると、同じ機能なのに処理結果が異なることもあります。

例えば、日付を表示用に変換する処理が複数の画面に書かれている場合は、共通の関数にまとめる方法があります。

共通化することで、修正する場所を1か所に減らせます。

ただし、少し似ているだけの処理を無理にまとめると、逆に分かりにくくなることもあります。

「本当に同じ役割の処理なのか」を確認してから整理することが大切です。

3．変数名や関数名を分かりやすくする

短い変数名は、コードを書くときには楽です。

しかし、

a = get_data()

b = update_data(a)

c = save_data(b)

というコードだけでは、それぞれに何が入っているのか分かりにくくなります。

例えば、

work_logs = load_work_logs()

updated_logs = calculate_work_time(work_logs)

save_work_logs(updated_logs)

と書けば、処理の内容を想像しやすくなります。

変数名や関数名を付けるときは、

・何が入っているのか

・何をする処理なのか

・単数なのか複数なのか

が伝わる名前にします。

長すぎる名前にする必要はありませんが、後から読んだときに内容が分かる名前を付けることが重要です。

4．設定値をコードの中に散らばらせない

ファイル名、保存先、URL、ポート番号などの設定値が、コードのいろいろな場所に直接書かれていることがあります。

例えば、

open("/home/user/data/work.csv")

という処理が複数の場所にある場合です。

保存先を変更するときに、すべてのコードを探して修正しなければなりません。

このような値は、設定ファイルや環境変数、定数などにまとめると管理しやすくなります。

ただし、パスワードやAPIキーなどの重要な情報は、コードへ直接書かないように注意が必要です。

5．コメントを書きすぎない

コードを分かりやすくするために、コメントをたくさん書けばよいと思われることがあります。

しかし、コードをそのまま説明しているだけのコメントは、なくても問題ない場合があります。

例えば、

# 合計金額を計算する

total_price = calculate_total_price(items)

というコメントは、関数名から処理を判断できます。

一方で、

・なぜこの処理が必要なのか

・なぜ通常とは違う方法を使っているのか

・どのような制約があるのか

といった内容は、コメントに残す価値があります。

コメントは「何をしているか」よりも、「なぜそうしているか」を書くと役立ちます。

6．使っていないコードを残しすぎない

修正前のコードを、念のためコメントアウトして残していることがあります。

しかし、古いコードが大量に残っていると、現在使われている処理がどれなのか分かりにくくなります。

また、使っていない関数や変数、import文が残っている場合もあります。

不要なコードは削除し、過去の内容を確認したい場合は、Gitなどのバージョン管理を利用する方法があります。

「いつか使うかもしれない」と残したコードが、実際には一度も使われないことも少なくありません。

7．修正する前に現在の動作を確認する

コードを整理する作業は、見た目をきれいにするだけではありません。

処理を分けたり、名前を変更したりすると、これまで動いていた機能に影響する可能性があります。

そのため、整理を始める前に、

・どの操作で何が起こるのか

・どのような結果が正しいのか

・どの機能を確認すればよいのか

を整理しておきます。

そして、コードを変更した後に、同じ操作を行って結果が変わっていないか確認します。

コード整理の目的は、機能を変えることではなく、現在の動きを保ったまま、分かりやすくすることです。

動いているうちに整理することが大切です

読みにくいコードでも、すぐに問題が起きるとは限りません。

しかし、機能追加や修正を重ねるほど、コードの構造は複雑になっていきます。

問題が起きてから整理しようとすると、どの部分を変更してよいのか分からず、作業に時間がかかることがあります。

そのため、

・同じ処理が増えてきた

・1つのファイルが長くなってきた

・修正する場所を探すのに時間がかかる

・AIに追加してもらったコードを理解できていない

・少し変更するだけでも不安

と感じた段階で、コードを整理することが大切です。

Pythonコードの整理や修正で困っている方へ

私は現役SEとして、Python、Flask、PostgreSQL、Ubuntu、Dockerなどを使った開発に携わっています。

ココナラでは、次のようなご相談に対応しています。

・読みにくくなったPythonコードの整理

・AIが生成したコードの確認と改善

・重複している処理の共通化

・関数やファイルへの分割

・不要なコードの整理

・既存機能を保ったままの修正

・エラー原因の調査

「動いているけれど、このまま使い続けてよいか不安」

「機能を追加しすぎて、自分では整理できなくなった」

「AIに作ってもらったため、コードの内容を理解できていない」

という場合でも、現在のコードと目的を確認しながら進めます。

最初からきれいなコードにする必要はありません。

今後も使い続けられる形へ、少しずつ整理していくことが大切です。

また、普段はPython、Flask、PostgreSQL、Ubuntu、Dockerなどについて、実際に試した内容や開発中に起きた問題を、初心者向けに発信しています。

今後も、プログラミングや開発で困ったときに役立つ内容を紹介していきます。