Je dois admettre que je ne suis pas d'accord avec certaines des choses que les autres réponses recommandaient, alors je vais jeter mes deux cents;
commentaires
La documentation est extrêmement utile pour les étrangers qui lisent votre code. Habituellement, beaucoup de choses ne sont pas suffisamment verbeuses pour être lues et comprises immédiatement, et vous devez ensuite expliquer ce que vous faites.
Edit : la discussion dans la section commentaire a souligné quelque chose de bien - les commentaires excessifs se font généralement lors de l'écriture de mauvais code.
Commenter votre travail doit être précis et minimal, mais, à mon avis, doit certainement être présent. Au moins un commentaire pour 15 lignes de code. Par exemple, au-dessus des blocs sur le code, ajoutez une ligne sur ce que vous faites:
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
Des commentaires minimaux qui expliquent pourquoi et ce que vous faites sont très utiles tout au long du code. Je ne suis pas d'accord avec la réponse qui dit
Si je tombe sur du code contenant des commentaires, je me prépare au pire: le code est susceptible d'être mauvais, et pour être honnête, les commentaires sont également susceptibles d'être mauvais.
Plusieurs fois, gracieusement, un bon code est documenté. Il est vrai que les mauvais programmeurs voient leur documentation comme "D'accord, mon code est mauvais, ajoutons quelques phrases pour le rendre plus clair".
Oui, et bien que cela se produise souvent, il est également vrai que les bons programmeurs qui écrivent du code propre veulent également s'assurer qu'ils reviennent à leur code et comprennent pourquoi ils veulent que leur fonction se comporte comme ça, ou pourquoi en ont-ils besoin ligne qui semble un peu redondante, etc ...
Oui, des commentaires qui expliquent des choses évidentes, des commentaires qui ne sont pas clairs, des commentaires qui ont juste été rassemblés pour s'assurer que "ce code est documenté, oui, peu importe", sont une odeur de code. Ils rendent la lecture du code plus difficile et irritante. (Ajout d'un exemple ci-dessous)
# Logging into Gmail when the module is imported
_client = login()
def get_client():
global _client
return _client
Exemple de clarification: "Pas de merde, Sherlock. Se _client = login()
connecte-t-il au service de messagerie? OMG!"
Plus de clarification: la login()
méthode n'a aucun rapport avec la login()
méthode de l'exemple ci-dessus.
Mais les commentaires qui correspondent aux normes, expliquent le pourquoi et non le comment, et répondent aux bonnes questions , sont très très ( très ) utiles.
Commentaires en ligne
Une chose que vous ne devriez PAS (et si je pouvais écrire plus gros, je le ferais), c'est d'écrire vos commentaires sur la même ligne du code. Cela rend les commentaires très spécifiques à la ligne, ce qui manque complètement l'objectif de commenter votre code.
Par exemple, de mauvais commentaires en ligne:
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
Serait beaucoup plus facile à lire et à comprendre ce code sans les commentaires, qui le rendent désordonné et illisible.
Au lieu de cela, les commentaires à l'intérieur de votre code doivent être placés au-dessus des blocs de code et répondre aux questions importantes qui peuvent survenir lors de la lecture du bloc de code.
# 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)
Beaucoup plus clair, non? Maintenant, vous savez également que vous devez utiliser la login()
fonction et fournir les paramètres à send_mail()
tout ce que vous avez utilisé. Aide un peu, mais il manque encore une chose.
Documentation fonction
A été largement discuté. Vous devez toujours faire savoir à vos lecteurs en quoi consiste votre fonction, pourquoi et ce qu'elle fait. Comment cela fait-il, cela n'appartient pas à la documentation, mais peut-être aux notes de bas de page de la fonction.
Vous devez décrire clairement ce que vous attendez de vos paramètres et si vous souhaitez qu'ils soient obtenus / créés dans une méthode spécifique. Vous devez déclarer ce que votre fonction doit renvoyer, son utilisation, etc.
Encore une fois, c'est mon opinion et ma méthodologie lors de l'écriture de mon code. Non seulement ceux-là, mais ce ne sont que quelques-unes des choses sur lesquelles je ne suis pas d'accord avec les autres réponses. Oh, et bien sûr, non seulement les commentaires lisent votre code, mais votre code lui-même. Écrivez du code propre, compréhensible et maintenable . Pensez à votre avenir en codant ;-)