前書き

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

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

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

Pythonのコメントは、ハッシュマーク( )と空白文字で始まり、行末まで続きます。

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

# This is a comment

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

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

hello.py

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

https://www.digitaloceanを反復処理するhttps://www.digitalocean.com/community/tutorials/how-to-construct-for-loops-in-python-3 [+ for + loop] com / community / tutorials / understanding-lists-in-python-3 [list]、コメントは次のようになります。

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)

コメントは、コメントしているコードと同じインデントで行う必要があります。 つまり、インデントのないhttps://www.digitalocean.com/community/tutorials/how-to-define-functions-in-python-3 [関数定義]には、インデントのないコメントと、各インデントレベルがあります。次のコメントは、コメントしているコードと整列しています。

たとえば、https://www.digitalocean.com/community/tutorials/how-to-make-a-simple-calculator-program-in-python-3の `+ again()+`関数がどのように機能するかを以下に示します。 [Python 3チュートリアルで簡単な電卓プログラムを作成する方法]にコメントがあり、コードの各インデントレベルの後にコメントがあります。

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プログラムで多くのhttps://www.digitalocean.com/community/tutorials/how-to-do-math-in-python-3-with-operators[math]を使用しない場合、あなたまたはあなたの共同編集者は、以下が複素数を生成することを知らない可能性があるため、それに関するインラインコメントを含めることができます。

z = 2.5 + 3j  # Create a complex number

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

x = 8  # Initialize x with an arbitrary number

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

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

ハッシュマークを使用すると、コードの設定方法を決定する際に別の方法を試すこともできます。 たとえば、https://www.digitalocean.com/community/tutorials/how-to-construct-while-loops-in-python-3 [+ while + loop]を使用するか、 `+ Pythonゲームで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のhttps://www.python.org/dev/peps/pep-0257/[PEP 257の文書文字列]を読んで、Pythonプロジェクトを適切に文書化するためのリソースを提供できます。