Pythonのコメントの書き方|複数行の書き方なども解説する

2022.07.10
スポンサーリンク

コメントは、どんなプログラムにも不可欠な要素です。

すべてのプログラミング言語はコメントを追加する方法を提供します。

Pythonのコメントシステムはとても簡単です。

このガイドでは、Pythonのコメントについて学びます。

スポンサーリンク

How to Write Comments in Python?

  • Python のコメントは # 文字で始まり、行の終わりまで続きます。
    Pythonのコメントは#文字で始まり、行末まで伸びる * 空白やコードの後、行頭からコメントを始めることができる。
  • ハッシュ文字が文字列リテラルに存在する場合、それは文字列の一部となります。

Python コメントの例

  • 変数に対するコメント
name = "Pankaj"  # employee name
id = 100  # employee id
 
data = "#123"  # this is comment, data contains # and that is not part of the comment.
  • 関数のコメント
# This function adds the two numbers
def add(x, y):
    return x+y
# This class provides utility functions to work with Strings
class StringUtils:
 
    def reverse(s):
        return ''.join(reversed(s))
  • クラスに関するコメント
# This class provides utility functions to work with Strings
# 1. reverse(s): returns the reverse of the input string
# 2. print(s): prints the string representation of the input object
class StringUtils:
 
    def reverse(s):
        return ''.join(reversed(s))
     
    def print(s):
        print(s)

Python Multiline Comment

コメントを1行で済ませることができない場合があります。

このような場合、コメントを複数行に分割することができます。

複数行のコメントを書くには、すべての行の前にハッシュ(#)を付けなければなりません。

def foo():
    """The foo() function needs to be implemented.
    Currently, this function does nothing."""
    pass
 
 
class Data:
    """ This class is used to hold Data objects information."""
print(foo.__doc__)
print(Data.__doc__)

Python の Docstring を複数行のコメントとして使用する

Python ドキュメント文字列 (Docstring) は、関数、クラス、モジュールのドキュメントを提供するために使用されます。

二重引用符 (“”) で囲まれた文字列で定義されます。


関数やクラスの宣言のすぐ下に定義する必要があります。

それでは、Pythonのdocstringの例をいくつか見てみましょう。

'''
This function read employees data from the database
emp_id: employee id, should be int
returns employee object.
'''
def read_emp_from_db(emp_id):
    i = int(emp_id)
    '''code to read emp data
    using the employee unique id number'''
    pass

あるエンティティの docstring には、 __doc__ 属性を使ってアクセスすることができます。

# count variable
count = 10
 
# foo() function
def foo():
    pass
# This function add two numbers
def foo(x, y):
    return x + y
 
 
# Better to have function defined as below. There is no use of comments.
 
def add_two_numbers(x, y):
    return x + y

複数行の長いコメントを指定するためにDocstringを使用するのは良いアイデアですか？

Python の docstring の目的は、ドキュメントを提供することです。

時々、長いコメントを提供するためにそれが誤用されていることに気づくでしょう。

しかし、それは推奨される方法ではありません。

もしコメントを複数行に分けたいなら、各行の前にハッシュ文字をつければいいのです。

この記事もチェック：Pythonでのコメントアウトのルールや複数行、範囲指定について解説する

Python の複数行の文字列を複数行のコメントとして扱う

複数行の文字列を複数行のコメントとして使用することもできます。

Guido氏のツイートによると、コードは生成されないそうです。

# {Object Type} - {Usage}
# Data Object - stores the Data fetched from the database
data_obj = Data()
 
 
# {Function Short Description}
# {Input Arguments and their types}
# {Return object details}
# {Exception Details}
 
# This function adds all the elements in the sequence or iterable
# numbers: sequence or iterable, all the elements must be numbers
# Returns the sum of all the numbers in the sequence or iterable
# Throws ArithmeticError if any of the element is not a number
 
 
def add_numbers(numbers):
    sum_numbers = 0
    for num in numbers:
        sum_numbers += num
    return sum_numbers

しかし、インデントがうまくいかないことがあります。

また、何の用途もない文字列がなぜコードの中に存在するのか、混乱します。

そこで、ハッシュ文字を使った通常の複数行コメントにこだわる方がよいでしょう。

Python コメントのベストプラクティス

  • エンティティの用途を指定するために、常に意味のあるコメントを記述してください。
  • 長いコメントは複数行に分けた方が良い。
  • コメントで失礼なことをしないようにしましょう。
  • コメントは要点を絞って書きましょう。誰もコードコメントで小説を読みたくはないでしょう。
  • 有用な情報を提供しない無駄なコメントは避けましょう。以下は、無駄なコメントの例です。
Python Comments
Python Comments
  • コメントは不要な場合もあります。実体の固有名詞があれば十分です。このシナリオの例を見てみましょう。
Python Multiline Comment
Python Multiline Comment
  • コメントシステムを導入するのは常に良いアイデアです。組織内で多くのチームメンバーや複数のプロジェクトで作業する場合、コメントポリシーを使用することが推奨されます。例えば、このようなコメントポリシーを定義することができます。
Python Docstrings
Python Docstrings

まとめ

  • Python のコメントシステムはシンプルで、常に # で始まります。
  • Python の docstring はドキュメントのためのものです。Pythonのdocstringはドキュメント用で、複数行のコメント用に誤用してはいけません。
  • 複数行のコメントのために、すべての行をハッシュ文字で開始します。
  • プログラム中にコメントを追加するためのベストプラクティスに従います。
  • 多くのチームメンバーで作業する場合、コメント付けのポリシーを持つことは常に良いアイデアです。
スポンサーリンク
タイトルとURLをコピーしました