アプリケーションの開発では、複数のファイルを誰が見ても分かるようにMECE Mutually(お互いに),Exclusive(重複せず),Collectively(全体に),Exhaustive(漏れがない)に管理する必要がある。フォルダの適切な階層構造・適切なファイル名・可読性とメンテナンス性が高いコード(コメント文を含む)の3つが重要である。
1. 開発用フォルダの準備
開発アプリケーションの規模が小さくない場合で、ファイルが主たるpyファイル以外に1つ以上存在する場合は、階層ごとにファイルの種類を管理するのが一般的である。場合によっては機能別に管理することもある。その場合、main()を含むファイルをmain.pyとする場合が多い。ごく小規模のアプリ開発でファイルが1つのみ場合は、機能を明確にした半角英数字の文字列+リビジョンにするのが良い(ex:03_study_opencv_01.py)。
2. ファイル名の付け方
ファイル名の参考例を以下に示す。Pythonやアプリケーション上で読み込むファイル名では基本的に半角英数字+アンダーバー”_”のみを使用する。特に、全角・半角のスペースは使用しない。ファイル名は数字から始めないのがベター。
- join_xlsx.py
- analysis_image.py
- setting_py_env4winpc.bat ※for(のための)を4と表記することが多い
- header_top_page.jpg
- top_app_icon.png
- btn_go_top.png ※ボタン(button)をbtnと表記することが多い
3. コードの推奨構成順序
下記はPythonのコピペ用おすすめテンプレート
# -*- coding: utf-8 -*-
# Python 3.7.4 # python --version を実行すると分かる
"""
author: serpent
creation datetime: 2021-12-18 18:08:13.375911
filename: 例[study_opencv_01.py]
function: 例[Arduinoからセンサ値読み取りでcsvファイル]
explanation:
1 例[変数port_serialにボーレートを入力]
2 例[シリアルポートを選択]
3 例[実行でarduinoからのセンサ値読み取り開始]
4 例[終了時csvファイルで自動保存]
5
"""
# ------------------------------------------------------------------- #
# --- 設定 ---------------------------------------------------------- #
# ------------------------------------------------------------------- #
import cv2
import datetime
# ---アプリ実行時間計測用--------------------------------------------- #
# time_start = datetime.datetime.now() # 上記のコメントdatetimeに記載する
# print(f"start:{time_start}")
# ---機能上のメイン処理----------------------------------------------- #
# - - - 変数・定数の定義 - - - - - - - - - - - - - - -
value_snake_case_01 = 1.1 # value_snake_case_01: float = 1.1
# - - - 関数の定義- - - - - - - - - - - - - - - - - -
# - - - main()の呼び出し- - - - - - - - - - - - - - -
# ------------------------------------------------------------------- #
# time_end = datetime.datetime.now()
# print(f"end:{time_end}")
# print(f"running_time:{time_end - time_start}")
print('done!')
# end_of_file: this line is 37th
- 1行目：使用文字コード(慣習的に必須)
- 2行目：使用Pythonのバージョン(慣習的に必須)：ターミナルでpython –version を実行すると確認できる
- 3行目以降：
ファイルの作成者
ファイルの最終更新日
ファイル名
ファイル(プログラム)の機能
プログラム内部の説明・使い方 - 16行目以降：
ライブラリーのimport
※importはプログラムの一番初めに実装すること - 21行目以降：
5行目に実行日時を記載するために入れている(本来、コード自体は不要)
32-34行目と合わせてプログラム全体の実行時間を計測可能。 - 24行目以降：
グローバル変数の定義・初期化定数の定義・#defineなどのプリコンパイル用文字列の定義(Pythonにはない概念) - 27行目以降：
自作の関数の定義(規模が大きく繰り返し同じ処理をするならばあると良い)
main()の定義(なくても良い) - 29行目以降：
if __name__ == “__main__”:の下にmain()を入れてエントリポイントとする
※main()を作らない場合は不要
※外部ファイルとして作成ファイルを呼び出す際は必須 - 35行目：プログラムが終了したことをチェックするためのprint文(本来は不要)
- 37行目：ファイルの最終行を確認するためのこの(本来は不要)
4. コメント文
適切なコメントをつけることで、可読性・メンテナンス性を高めることができる。というより、昨日の自分・明日の自分は他人という認識でコメントを残していくと良い。
下記のリンクにサンプルプログラムを記載しておくので参照されたし。
EOF