Python コードの可読性を向上させるための 5 つの重要なヒント

翻訳者 | Zhao Qingyu

レビュアー | Sun Shujuan

6 か月前に書いたコードをよく見直して、このコードで何が起こっているのか知りたいと思いますか? または他の人のプロジェクトに興味があって、どこから始めればよいかわからない? この状況は開発者にとって比較的一般的です。 Python には、コードの内部動作を理解するのに役立つメソッドが多数あるため、コードを最初から確認したり、コードを作成したりするときに、中断したところから続けるのが簡単になるはずです。

ここで例を挙げますと、以下のようなコードが得られると思います。これは最悪のことではありませんが、確認する必要があることがいくつかあります。

• load_las_file 関数の f と d は何を表しますか?
• なぜ確認する必要があるのですか?クレイ関数で実行しますか? 結果を確認してください?
• これらの関数にはどのようなタイプが必要ですか? Float または DataFrame?

この記事では、ドキュメント、プロンプト入力、適切な変数名を通じてアプリケーション/スクリプトの読みやすさを向上させる方法に関する 5 つの基本的なヒントについて説明します。 。

1. コメント

コードに対して最初にできることは、特定の行にコメントを追加することですが、コメントしすぎないように注意してください。コメントでは、コードの実装方法ではなく、コードが機能する理由、または特定の方法で実行される理由を説明する必要があります。 Python のコメントは通常、シャープ記号 (#) を使用して完成します。これは 1 行または複数行にまたがることができます。

# Comment using the hashtag
# Another comment using the hashtag

複数行のコメントの場合は、二重引用符を使用することもできます。

"""
This is an example of
a multi-line comment
"""

以下の例では、コードの特定の行がどのように機能するか、およびその理由を説明するためにコードにいくつかのコメントが追加されています:

2. 表示タイプ型付け

Python 言語は動的に型付けされます。つまり、変数の型は実行時にのみチェックされます。さらに、変数はコードの実行中に型を変更する可能性があります。一方、静的型付けでは変数の型を明示的に宣言する必要があり、コードの実行中に変更することはできません。

2014 年に PEP 484 で型ヒントの概念が導入され、その後 Python 3.5 に導入されました。これにより、変数の型を明示的に宣言できるようになります。タイプヒントを追加すると、コードの読みやすさが大幅に向上します。次の例では、次のことがわかります。

• 2 つのパラメータが必要です。
• パラメータ ファイル名のタイプは文字列です。
• パラメータ start_ Depth のタイプは、 float 型、このパラメータのデフォルト値は None です
• この関数は pandas DataFrame オブジェクトを返します

型ヒントによると、関数が何を要求し、何を返すのかを正確に知ることができます。

3. ドキュメント文字列

ドキュメント文字列は、関数またはクラス定義の直後に続く文字列です。 docstring は、関数の動作、関数が受け取る引数、スローする例外、戻り値などを詳細に説明する優れた方法です。さらに、Sphinx などのツールを使用してコードのオンライン ドキュメントを作成すると、ドキュメント文字列が自動的に抽出され、適切なドキュメントに変換されます。次の例は、clay_volume という名前の関数の docstring を示しています。ここで各パラメータの意味を指定できます。これにより、基本的な型ヒントよりも詳細になります。学術的な参考文献や方程式など、関数の背後にある方法論に関する詳細情報を含めることもできます。

#ドキュメント文字列は、コード内の他の場所で関数を呼び出すときにも非常に役立ちます。たとえば、Visual Studio を使用してコードを作成する場合、関数呼び出しの上にマウスを置くと、関数の動作と関数に必要な内容を示すポップアップが表示されます。

Visual Studio Code (VS Code) を使用して Python コードを編集する場合は、autoDocstring などの拡張機能を使用して、docstring の作成プロセスを容易にすることができます。二重引用符を 3 つ入力すると、テンプレートの残りの部分が自動的に入力されます。詳細を入力するだけです。

ヒント: パラメーターで型を宣言した場合、それらは自動的に選択されます。

4. 読みやすい変数名

コードを書いているとき、特に時間がないときは、変数の名前をあまり気にしないことがあります。ただし、コードに戻って見て、x1 または var123 という名前の一連の変数を見つけた場合、一見しただけではそれらが何を表しているのか理解できないかもしれません。以下の例には、2 つの変数 f と d があります。コードの他の部分を確認することで、このような変数の意味を推測できますが、特にコードが長い場合は時間がかかることがあります。

これらの変数に適切な名前を付けると、変数の 1 つが lasio.read() 呼び出しによって読み取られた data_file であることがわかります。おそらく元のデータです。データ変数は、これが扱っている実際のデータであることを示します。

5. マジック ナンバーを避ける

マジック ナンバーとは、背後に説明のつかない意味を持つコード内の値であり、定数である場合もあります。コードでこれらを使用すると、特に計算での数値の使用に慣れていない場合、あいまいさが生じる可能性があります。さらに、同じマジックナンバーが複数の場所にある場合、それを更新する必要がある場合、そのすべてのインスタンスを更新する必要があります。ただし、そのような数値に適切な名前の変数が割り当てられている場合、置換プロセスははるかに簡単になります。以下の例では、result という値を計算し、0.6 で乗算する関数があります。これは何を意味しますか? それは変換係数ですか? スカラーですか?

変数を宣言してそれに値を代入すると、それが何であるかがわかる可能性が高くなります。この場合、粘土と頁岩の比を使用して、ガンマ線指数を粘土の体積に変換します。

6. 最終コード

上記のヒントを適用すると、最終コードはよりきれいになり、理解しやすくなります。

7. 概要

コメントや docstring を通じてコードに説明を追加すると、自分や他の人がコードの動作を理解するのに役立ちます。最初は面倒に感じるかもしれませんが、ツールを使用し、定期的に練習することで、自然にできるようになります。

元のリンク: https://towardsdatascience.com/5-essential-tips-to-improve-the-readability-of-your-python-code-a1d5e62a4bf0

翻訳者の紹介

51CTO コミュニティ編集者である Zhao Qingyi は、長年ドライバー開発に従事してきました。彼の研究対象にはセキュア OS およびネットワーク セキュリティ分野が含まれており、ネットワーク関連の特許を公開しています。

以上がPython コードの可読性を向上させるための 5 つの重要なヒントの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。