Python コメントを正しい方法で作成する

コメントは、プログラマーがコードに付けて、そのコードが何をすべきかを説明するメモです。 コードをアクションに変換するコンパイラまたはインタープリターはコメントを無視しますが、ソフトウェア プロジェクトの管理には不可欠な場合があります。

コメントは、Python コードを他のプログラマーに説明するのに役立ち、選択した理由を思い出すことができます。 コメントは、将来のプログラマーがソフトウェアの背後にある設計上の選択を理解するのに役立ち、コードのデバッグと修正を容易にします。

コメントは主に開発者向けですが、効果的なコメントを書くことは、コードのユーザー向けに優れたドキュメントを作成するのにも役立ちます。 Python プロジェクト用の Sphinx などのドキュメント ジェネレーターの助けを借りて、コード内のコメントでドキュメントのコンテンツを提供できます。

Python でのコメントの内部を見てみましょう。

Python でのコメント

Python PEP 8 Style Guide によると、コメントを書く際に留意すべき点がいくつかあります。

• コメントは常に完全で簡潔な文章にする必要があります。
• 理解が難しい、または不正確なコメントよりも、コメントがない方がよいでしょう。
• コードの変更を反映するために、コメントは定期的に更新する必要があります。
• コメントが多すぎると、気が散り、コードの品質が低下する可能性があります。 コードの目的が明らかな場合、コメントは必要ありません。

Python では、 #記号で始まる行はコメントとして宣言されます。 Python インタープリターは、コード内で#を検出すると、そのシンボル以降を無視し、エラーを生成しません。 単一行コメントを宣言するには、インライン コメントとブロック コメントの 2 つの方法があります。

インラインコメント

インライン コメントは、変数と簡単な操作の簡単な説明を提供し、コード ステートメントと同じ行に記述されます。

 border = x + 10 # Make offset of 10px

コメントは、コードと同じステートメント内のコードの機能を説明します。

ブロックコメント

ブロック コメントは、コード内の複雑なロジックを記述するために使用されます。 Python のブロック コメントは、インライン コメントと同様に作成されます — 唯一の違いは、ブロック コメントが別の行に記述されることです。

 import csv from itertools import groupby # Get a list of names in a sequence from the csv file with open('new-top-firstNames.csv') as f: file_csv = csv.reader(f) # Skip the header part: (sr, name, perc) header = next(file_csv) # Only name from (number, name, perc) persons = [ x[1] for x in file_csv] # Sort the list by first letter because # The groupby function looks for sequential data. persons.sort(key=lambda x:x[0]) data = groupby(persons, key=lambda x:x[0]) # Get every name as a list data_grouped = {} for k, v in data: # Get data in the form # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]} data_grouped[k] = list(v)

ブロック コメントを使用する場合、コメントは説明しているコードの上に記述されることに注意してください。 Python PEP8 スタイル ガイドでは、1 行のコードに 79 文字を超えてはならないと規定されており、インライン コメントによって行がこの長さを超えることがよくあります。 これが、コードを別の行に記述するためにブロック コメントが記述される理由です。

複数行のコメント

Python は複数行のコメントをネイティブにサポートしていません。つまり、複数行のコメントを定義するための特別な規定はありません。 それにもかかわらず、複数行にわたるコメントがよく使用されます。

各行の先頭に#を付けることで、複数の単一行コメントから複数行コメントを作成できます。

 # interpreter # ignores # these lines

複数行の文字列構文も使用できます。 Python では、複数行の文字列を""" 、3 つの二重引用符、または''' 、3 つの単一引用符で囲むことによって定義できます。

 print("Multi-Line Comment") """ This String is Multi line """

上記のコードでは、複数行の文字列が変数に割り当てられていないため、文字列はコメントのように機能します。 実行時に、Python は文字列を無視し、バイトコードに含まれません。 上記のコードを実行すると、次の出力が生成されます。

 Multi-Line Comment

特記事項

コメントは、コードを読みやすくするだけでなく、将来のコード追加の計画やドキュメントの生成など、Python でいくつかの特別な目的にも役立ちます。

Python Docstring コメント

Python では、docstring は、特定の関数またはクラスの使用方法を説明する複数行のコメントです。 高品質のドキュメント文字列を作成することで、コードのドキュメントが改善されます。 関数またはクラスを操作し、組み込みのhelp(obj)関数を使用する場合、docstring はオブジェクトの概要を示すのに役立つ場合があります。

Python PEP 257 は、以下に示すように、Python で docstring を宣言する標準的な方法を提供します。

 from collections import namedtuple Person = namedtuple('Person', ['name', 'age']) def get_person(name, age, d=False): """ Returns a namedtuple("name", "age") object. Also returns dict('name', 'age') if arg `d` is True Arguments: name – first name, must be string age – age of person, must be int d – to return Person as `dict` (default=False) """ p = Person(name, age) if d: return p._asdict() return p

上記のコードでは、関連付けられた関数の動作に関する詳細が docstring によって提供されています。 Sphinx のようなドキュメント ジェネレーターでは、この docstring を使用して、プロジェクトのユーザーにこのメソッドの使用方法の概要を提供できます。

関数またはクラス シグネチャのすぐ下で定義された docstring は、組み込みのhelp()関数を使用して返すこともできます。 help()関数は、オブジェクトまたは関数名を引数として取り、関数の docstring を出力として返します。 上記の例では、 help(get_person)を呼び出して、 get_person関数に関連付けられた docstring を表示できます。 -iフラグを使用して対話型シェルで上記のコードを実行すると、この docstring が Python によってどのように解析されるかを確認できます。 python -i file.pyと入力して、上記のコードを実行します。

help(get_person)関数呼び出しは、関数の docstring を返します。 出力には、Python が自動的に追加する関数シグネチャであるget_person(name, age, d=False)が含まれます。

get_person.__ doc__属性を使用して、docstring をプログラムで取得および変更することもできます。 上記の例に「いくつかの新しい情報」を追加すると、 help(get_person)の 2 回目の呼び出しに表示されます。 それでも、このように実行時に docstring を動的に変更する必要はほとんどありません。

TODO コメント

コードを書くとき、改善のために特定の行またはブロック全体を強調表示したい場合があります。 これらのタスクは、TODO コメントによってフラグが付けられます。 TODO コメントは、コードの更新や変更を計画している場合、またはプロジェクトのユーザーや共同作業者に、ファイルのコードの特定のセクションが残っていることを知らせたい場合に便利です。

TODO コメントは疑似コードとして記述すべきではありません。まだ記述されていないコードの機能を簡単に説明するだけです。

TODO コメントと単一行ブロック コメントは非常に似ており、両者の唯一の違いは、TODO コメントは TODO プレフィックスで始まる必要があることです。

 # TODO Get serialized data from the CSV file # TODO Perform calculations on the data # TODO Return to the user

多くの IDE はプログラマー向けにこれらのコメントを強調表示できますが、Python インタープリターは TODO コメントをブロック コメントとまったく異なる方法で表示しないことに注意することが重要です。

Python コメントを記述する際のベスト プラクティス

信頼性と品質を確保するために、コメントを書く際に従うべきベスト プラクティスがいくつかあります。 以下は、Python で質の高いコメントを書くためのヒントです。

明白なことを避ける

明らかなことを述べているコメントは、コードに価値を追加しないため、避ける必要があります。 例えば：

 x = x + 4 # increase x by 4

このコメントは、コードが何をする必要があるかを説明せずにコードが何をするかを単に述べているだけなので、役に立ちません。 コメントは、記述しているコードの「何」ではなく、「なぜ」を説明する必要があります。

より便利に書き直すと、上記の例は次のようになります。

 x = x + 4 # increase the border width

Python のコメントは短く簡潔に保つ

コメントは短く、理解しやすいものにしてください。 それらは疑似コードではなく標準的な散文で書かれるべきであり、それが何をするかの一般的な概要を得るために実際のコードを読む必要性を置き換えるべきです。 詳細または複雑なコメントが多すぎると、プログラマーの仕事が簡単にはなりません。 例えば：

# return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r) def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

上記のコメントは、読者にとって必要以上の情報を提供しています。 コア ロジックを指定する代わりに、コメントはコードの一般的な概要を提供する必要があります。 このコメントは次のように書き換えることができます。

 # return area of cylinder def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

識別子を慎重に使用する

識別子は、コメントで慎重に使用する必要があります。 識別子の名前やケースを変更すると、読者が混乱する可能性があります。 例：

 # return class() after modifying argument def func(cls, arg): return cls(arg+5)

上記のコメントはclassとargumentに言及していますが、どちらもコードにはありません。 このコメントは次のように書き換えることができます。

 # return cls() after modifying arg def func(cls, arg): return cls(arg+5)

ドライとウェット

コードを書くときは、DRY (同じことを繰り返さない) の原則に従い、WET (すべてを 2 回書く) を避ける必要があります。

これはコメントにも当てはまります。 コードを記述するために複数のステートメントを使用することは避け、同じコードを説明するコメントを 1 つのコメントにマージするようにしてください。 ただし、コメントをマージするときは注意が必要です。複数のコメントを不注意にマージすると、スタイル ガイドに違反し、読者が理解するのが難しい巨大なコメントになる可能性があります。

コメントはコードの読み取り時間を短縮する必要があることに注意してください。

 # function to do x work def do_something(y): # x work cannot be done if y is greater than max_limit if y < 400: print('doing x work')

上記のコードでは、コメントが不必要に断片化されているため、1 つのコメントにマージできます。

 # function to do x if arg:y is less than max_limit def do_something(y): if y in range(400): print('doing x work')

一貫したインデント

コメントが記述しているコードと同じレベルでインデントされていることを確認してください。 そうでない場合、フォローするのが難しい場合があります。

たとえば、次のコメントはインデントされていないか、適切に配置されていません。

 for i in range(2,20, 2): # only even numbers if verify(i): # i should be verified by verify() perform(x)

次のように書き換えることができます。

 # only even numbers for i in range(2,20, 2): # i should be verified by verify() if verify(i): perform(x)

概要

コメントは、理解しやすいコードを記述するための重要なコンポーネントです。 コメントを書くための投資は、将来のあなた自身、またはあなたのコード ベースで作業する必要がある他の開発者にとってありがたいものです。 コメントを付けることで、コードをより深く理解することもできます。

このチュートリアルでは、さまざまな種類の Python コメント、それぞれをいつ使用するか、コメントを作成する際に従うべきベスト プラクティスなど、Python のコメントについて詳しく学習しました。

良いコメントを書くことは、研究して開発する必要があるスキルです。 コメントを書く練習をするには、以前のプロジェクトに戻ってコメントを追加することを検討してください。 インスピレーションを得て、実際のベスト プラクティスを確認するには、GitHub で十分に文書化された Python プロジェクトをチェックしてください。

独自の Python プロジェクトをライブにする準備ができたら、Kinsta のアプリケーション ホスティング プラットフォームはコードを GitHub からクラウドに数秒で取得できます。