Я мушу визнати, що я не згоден з деякими речами, на які рекомендували інші відповіді, тому я збираюся кинути свої два центи;
Коментарі
Документація надзвичайно корисна для незнайомців, які читають ваш код. Зазвичай багато речей не будуть достатньо багатослівними, щоб їх можна було прочитати та зрозуміти негайно, і тоді вам слід пояснити, що ви робите.
Редагувати : обговорення в розділі коментарів вказало на щось правильно - надмірно коментування зазвичай робиться під час написання поганого коду.
Коментуючи свою роботу має бути точним та мінімальним, але, на мою думку, обов’язково має бути присутнім. Принаймні коментар кожні 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()увійде в поштову службу? OMG!"
Більше уточнення: 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()всім, що ви використовували. Допомагає трохи, але одне все одно відсутнє.
Функціональна документація
Широко обговорювалося. Ви завжди повинні повідомляти вашим читачам, у чому полягає ваша функція, чому і що вона робить. Як це робиться, це не належить до документації, але, можливо, виноски функції.
Ви повинні чітко описати, які очікують ваші параметри, і якщо ви хочете, щоб вони були отримані / створені певним методом. Вам слід оголосити, яку функцію має повернути, якою є її використання тощо.
Знову ж таки, це моя думка та методологія під час написання мого коду. Не лише ті, але й лише деякі з тих речей, про які я не міг погодитися з іншими відповідями. Ну, і звичайно, не просто коментарі читають ваш код, але і сам код. Написати чистий код, зрозумілий і ремонтопрігодни . Подумайте про своє майбутнє, кодуючи ;-)