How To Write Comments in Python 3

投稿日: 2019-11-08 2022-04-20
タグ: Development, python

序章

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

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

一般に、プログラムを書いたり更新したりしているときにコメントを書くことは良い考えです。後で考えたプロセスを忘れがちであり、後で書いたコメントは長期的には役に立たなくなる可能性があります。

前提条件

Python 3をインストールし、コンピューターまたはサーバーにプログラミング環境をセットアップする必要があります。プログラミング環境をセットアップしていない場合は、ローカルプログラミング環境またはサーバー上のプログラミング環境のインストールおよびセットアップガイドを参照して、オペレーティングに適したものにすることができます。システム（Ubuntu、CentOS、Debianなど）

コメント構文

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

情報：このチュートリアルのサンプルコードに従うには、python3コマンドを実行して、ローカルシステムでPythonインタラクティブシェルを開きます。次に、>>>プロンプトの後に例を追加して、例をコピー、貼り付け、または編集できます。

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

# This is a comment

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

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

hello.py

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

リストを反復処理するforループでは、コメントは次のようになります。

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)

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

たとえば、 Python 3チュートリアルで簡単な電卓プログラムを作成する方法のagain()関数にコメントを付け、コードの各インデントレベルの後にコメントを付けます。

計算機.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ループまたは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プロジェクトを適切に文書化するためのより多くのリソースを提供するために、PEP257のPythonのDocstringsについて読むことができます。

getdocs

13036