私は、他の答えが推奨したことのいくつかに同意しないことを認めなければならないので、2セントを投げるつもりです。
コメント
ドキュメンテーションは、コードを読んでいる見知らぬ人にとって非常に役立ちます。通常、多くのことはすぐに読んで理解できるほど冗長ではないので、何をしているのかを説明する必要があります。
編集：コメントセクションの議論は何か正しいことを指摘しました。通常、悪いコメントを書くときは過剰コメントをします。
あなたの作品にコメントすることは正確かつ最小限でなければなりませんが、私の意見では、間違いなく存在するべきです。コードの15行ごとに少なくともコメント。たとえば、コードのブロックの上に、実行していることに関する行を追加します。
def login(username: str, password: str, create_session: bool = True):
# Filter the user we need from the database
hash = md5(password)
users = db.table("users", db_entities.USER)
results = [x for x in users.query(lambda c: c.get("username") == username and c.get("password_hash") == hash)]
if len(results) == 0:
return None, None
else:
# Create a login session record in the database.
if create_session:
sessions = db.table("sessions", db_entities.SESSION)
ses = sessions.new()
ses.set("username", username) \
.set("expiery", 31536000 + time.time())
sessions.update(ses)
return results[0], ses
else:
return results[0], None
なぜ、何をしているかを説明する最小限のコメントは、コード全体で非常に役立ちます。次のような答えには同意しません
コメントを含むコードに出くわした場合、最悪の事態に備えます。コードが悪い可能性が高く、正直なところ、コメントも悪い可能性が高いです。
多くの場合、優雅に、良いコードが文書化されています。悪いプログラマーが「わかりました、私のコードは悪いです。わかりやすくするためにいくつかの文章を追加しましょう」のようなドキュメントを見るのは事実です。
はい、これはかなり頻繁に発生しますが、きれいなコードを書く優秀なプログラマーは、自分のコードに戻り、関数をそのように動作させたい理由、またはなぜそれを必要としたのかを理解したいことも事実です少し冗長に思える行など
はい、明白なことを説明するコメント、不明瞭なコメント、「このコードが文書化されていることを確認するためにまとめられたコメント」はコード臭です。彼らはコードを読むのを難しくし、いらいらさせます。（以下に例を追加）
# Logging into Gmail when the module is imported
_client = login()
def get_client():
global _client
return _client
明確化の例：「たわごと、Sherlock。_client = login()メールサービスにログインしますか？OMG！」
より明確な説明：login()メソッドはlogin()、上記の例のメソッドとは関係ありません。
しかし、基準と一致し、理由ではなく理由を説明し、正しい質問に答えるコメントは、非常に（非常に）役に立ちます。
インラインコメント
してはいけないことの1つは（そして、もっと大きく書くことができるなら）、コードの同じ行にコメントを書くことです。それはコメントを非常に行固有にし、コードをコメントする目的を完全に逃します。
たとえば、悪いインラインコメント：
outer = MIMEText(details["message"]) # Constructing a new MIMEText object
outer["To"] = details["to"] # Setting message recipient
outer["From"] = "xAI No-Reply" # Setting message sender
outer["Subject"] = details["subject"] # Setting message subject
outer.preamble = "You will not see this in a MIME-aware mail reader.\n" # I don't know what I'm doing here, I copied this from SO.
msg = outer.as_string() # Getting the string of the message
_client = details["client"] # Assigning the client
_client.sendmail(SENDER, details["to"], msg) # Sending the mail
コメントなしでこのコードを読みやすく理解すると、コードが乱雑で読みにくくなります。
代わりに、コード内のコメントをコードのブロックの上に配置し、コードブロックの読み取り中に発生する可能性のある重要な質問に答える必要があります。
# Constructing the email object with the values
# we received from the parameter of send_mail(details)
outer = MIMEText(details["message"])
outer["To"] = details["to"]
outer["From"] = "xAI No-Reply"
outer["Subject"] = details["subject"]
outer.preamble = "You will not see this in a MIME-aware mail reader.\n"
msg = outer.as_string()
# Sending the mail using the global client (obtained using login())
_client = details["client"]
_client.sendmail(SENDER, details["to"], msg)
はるかに明確ですよね？これで、login()関数を使用し、使用send_mail()したすべてのパラメーターを提供する必要があることもわかりました。少し助けになりますが、まだ一つ欠けていることがあります。
機能ドキュメント
広く議論されています。あなたは常にあなたの読者にあなたの機能が何であるか、なぜ、何をするのかを知らせるべきです。それがどのように行われるかは、これはドキュメントに属するのではなく、関数の脚注に属する可能性があります。
パラメーターが何であるか、また特定の方法でパラメーターを取得/作成する場合は、明確に記述する必要があります。関数が返すもの、その使用方法などを宣言する必要があります。
繰り返しますが、それは私のコードを書いている間の私の意見と方法論です。それらだけでなく、これらは私が他の答えに同意できなかったもののほんの一部です。ああ、もちろん、コメントだけでコードが読み取られるのではなく、コード自体が読み取られます。わかりやすく保守可能なクリーンなコードを作成します。コーディング中に自分の将来について考えてください;-)