Python 3でコメントを書く方法

前書き

コメントは、コンパイラーおよびインタープリターによって無視されるコンピュータープログラムに存在する行です。プログラムにコメントを含めると、プログラムの各部分が何をしているかについての情報または説明が提供されるため、人間にとってコードが読みやすくなります。

プログラムの目的に応じて、コメントは自分自身やリマインダーへのメモとして機能したり、他のプログラマーがコードの実行内容を理解できるように作成したりできます。

一般的に、プログラムの作成中または更新中にコメントを書くことは、後で思考プロセスを忘れやすいため、良いアイデアです。また、後で書いたコメントは、長期的にはあまり役に立たない可能性があります。

Pythonのコメントは、ハッシュマーク（#）と空白文字で始まり、行の終わりまで続きます。

通常、コメントは次のようになります。

# This is a comment

コメントは実行されないため、プログラムを実行しても、コメントの表示は表示されません。コメントは、コンピューターが実行するのではなく、人間が読むためのソースコードにあります。

「Hello、World！」プログラムでは、コメントは次のようになります。

hello.py

# Print “Hello, World!” to console
print("Hello, World!")

listを反復処理するfor loopでは、コメントは次のようになります。

sharks.py

# Define sharks variable as a list of strings
sharks = ['hammerhead', 'great white', 'dogfish', 'frilled', 'bullhead', 'requiem']

# For loop that iterates over sharks list and prints each string item
for shark in sharks:
   print(shark)

コメントは、コメントしているコードと同じインデントで行う必要があります。つまり、インデントのないfunction definitionには、インデントのないコメントがあり、後続の各インデントレベルには、コメントしているコードに合わせたコメントがあります。

たとえば、How To Make a Simple Calculator Program in Python 3 tutorialのagain()関数にコメントを付け、コードの各インデントレベルの後にコメントを付ける方法を次に示します。

calculator.py

...
# Define again() function to ask user if they want to use the calculator again
def again():

    # Take input from user
    calc_again = input('''
Do you want to calculate again?
Please type Y for YES or N for NO.
''')

    # If user types Y, run the calculate() function
    if calc_again == 'Y':
        calculate()

    # If user types N, say good-bye to the user and end the program
    elif calc_again == 'N':
        print('See you later.')

    # If user types another key, run the function again
    else:
        again()

コメントは、元のプログラマであろうと、プロジェクトで使用または共同作業しているプログラマであろうと、プログラマを支援するために作成されます。コメントをコードベースと共に適切に維持および更新できない場合は、コードと矛盾する、または矛盾するコメントを書くよりも、コメントを含めない方が良いでしょう。

コードにコメントを付けるときは、whatまたはhowではなく、コードの背後にあるwhyに答えることを検討する必要があります。コードが特にトリッキーでない限り、コードを見ると、一般的にコードが何をしているのか、またはどのように実行しているのかを知ることができます。

ブロックコメントを使用すると、より複雑なコードや、読者がなじみのないコードを説明できます。これらの長い形式のコメントは、後続のコードの一部またはすべてに適用され、コードと同じレベルでインデントされます。

ブロックコメントでは、各行はハッシュマークと単一のスペースで始まります。複数の段落を使用する必要がある場合は、単一のハッシュマークを含む行で区切る必要があります。

以下に定義されているmain()関数で何が起こっているかを定義するブロックコメントの例を次に示します。

# The main function will parse arguments via the parser variable.  These
# arguments will be defined by the user on the console.  This will pass
# the word argument the user wants to parse along with the filename the
# user wants to use, and also provide help text if the user does not
# correctly pass the arguments.

def main():
  parser = argparse.ArgumentParser()
  parser.add_argument(
      "word",
      help="the word to be searched for in the text file."
  )
  parser.add_argument(
      "filename",
      help="the path to the text file to be searched through"
  )
...

ブロックコメントは、通常、操作がそれほど単純ではないため、詳細な説明が必要な場合に使用されます。コードを過度にコメントしないようにしてください。また、特定の対象者向けに書かない限り、他のプログラマーがPythonを理解することを信頼する傾向があります。

インラインコメントは、コード自体に続いて、ステートメントの同じ行で発生します。他のコメントと同様に、それらはハッシュマークと単一の空白文字で始まります。

一般に、インラインコメントは次のようになります。

[code]  # Inline comment about the code

インラインコメントは控えめに使用する必要がありますが、コードのトリッキーな部分や非自明な部分の説明には効果的です。また、将来書いているコードの行を覚えていないかもしれないと思う場合、またはコードのすべての側面に精通していないかもしれない知っている誰かと協力している場合にも役立ちます。

たとえば、Pythonプログラムで多くのmathを使用しない場合、あなたまたは共同編集者は、以下が複素数を作成することを知らない可能性があるため、それに関するインラインコメントを含めることができます。

z = 2.5 + 3j  # Create a complex number

次のように、インラインコメントを使用して、何かを実行する背後にある理由や追加情報を説明することもできます。

x = 8  # Initialize x with an arbitrary number

インラインで作成されたコメントは、必要な場合と、プログラムを読んでいる人に役立つガイダンスを提供できる場合にのみ使用してください。

コードを文書化する方法としてコメントを使用することに加えて、ハッシュマークを使用して、現在作成中のプログラムのテストまたはデバッグ中に実行したくないコードをコメントアウトすることもできます。つまり、新しいコード行を実装した後にエラーが発生した場合、それらのいくつかをコメントアウトして、正確な問題をトラブルシューティングできるかどうかを確認できます。

ハッシュマークを使用すると、コードの設定方法を決定する際に別の方法を試すこともできます。たとえば、Pythonゲームでwhile loopループとforループのどちらを使用するかを決定している場合、どちらが最適かをテストおよび決定するときに、どちらか一方をコメントアウトできます。

guess.py

import random

number = random.randint(1, 25)

# number_of_guesses = 0

for i in range(5):
# while number_of_guesses < 5:
    print('Guess a number between 1 and 25:')
    guess = input()
    guess = int(guess)

    # number_of_guesses = number_of_guesses + 1

    if guess < number:
        print('Your guess is too low')

    if guess > number:
        print('Your guess is too high')

    if guess == number:
        break

if guess == number:
    print('You guessed the number!')

else:
    print('You did not guess the number. The number was ' + str(number))

ハッシュマークを使用してコードをコメントアウトすると、プログラムの一部を体系的にコメントアウトして実行することにより、さまざまなプログラミング方法を試すことができ、エラーの原因を見つけることができます。

結論

Pythonプログラム内でコメントを使用すると、将来の自己を含め、プログラムを人間にとって読みやすくするのに役立ちます。関連性があり有用な適切なコメントを含めると、他の人がプログラミングプロジェクトであなたと協力しやすくなり、コードの価値がより明確になります。

ここから、PythonのDocstrings in PEP 257について読んで、Pythonプロジェクトを適切に文書化するためのより多くのリソースを提供することができます。

TOC

Python 3でコメントを書く方法

前書き

結論

Related