Я должен признать, что я не согласен с некоторыми вещами, которые рекомендовали другие ответы, поэтому я собираюсь бросить свои два цента;
Комментарии
Документация чрезвычайно полезна для незнакомых людей, читающих ваш код. Обычно многие вещи не достаточно многословны, чтобы их можно было сразу же прочитать и понять, и вам следует объяснить, что вы делаете.
Изменить : обсуждение в разделе комментариев указал на что-то правильное - чрезмерное комментирование обычно делается при написании плохого кода.
Комментирование вашей работы должно быть точным и минимальным, но, на мой взгляд, обязательно должно присутствовать. Как минимум комментарий для каждых 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
Пример пояснения: "Не дерьмо, Шерлок. _client = login()Вход в почтовый сервис? О Боже!"
Дополнительные пояснения: login()метод не имеет отношения к login()методу из приведенного выше примера.
Но комментарии, которые соответствуют стандартам, объясняют, почему, а не как, и отвечают на правильные вопросы , очень ( очень ) полезны.
Встроенные комментарии
Одна вещь, которую вы НЕ ДОЛЖНЫ (и если бы я мог написать это больше), это написать свои комментарии в той же строке кода. Это делает комментарии очень специфичными для строк, что полностью не соответствует цели комментирования вашего кода.
Например, плохие встроенные комментарии:
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()всего, что вы использовали. Помогает немного, но одна вещь все еще отсутствует.
Документация по функциям
Был широко обсужден. Вы всегда должны сообщать своим читателям, о чем ваша функция, почему и что она делает. Как это происходит, это относится не к документации, а, возможно, к сноскам функции.
Вы должны четко описать, что вы ожидаете от ваших параметров, и хотите ли вы, чтобы они были получены / созданы определенным методом. Вы должны указать, что должна возвращать ваша функция, как ее использовать и т. Д.
Опять же, это мое мнение и методология при написании моего кода. Не только те, но это только некоторые из вещей, о которых я не мог согласиться с другими ответами. О, и, конечно, не только комментарии читают ваш код, но и сам код. Написать чистый код, понятный и обслуживаемый . Думайте о своем будущем я, кодируя ;-)