Ich muss zugeben, dass ich mit einigen Dingen, die in den anderen Antworten empfohlen wurden, nicht einverstanden bin, also werfe ich meine zwei Cent.
Bemerkungen
Die Dokumentation ist für Fremde, die Ihren Code lesen, äußerst hilfreich. Normalerweise sind viele Dinge nicht ausführlich genug, um sofort gelesen und verstanden zu werden, und Sie sollten dann erklären, was Sie tun.
Bearbeiten : Die Diskussion im Kommentarbereich hat auf etwas Richtiges hingewiesen - Überkommentierung wird normalerweise durchgeführt, wenn fehlerhafter Code geschrieben wird.
Das Kommentieren Ihrer Arbeit sollte präzise und minimal sein, aber meiner Meinung nach sollte es definitiv vorhanden sein. Mindestens ein Kommentar für jeweils 15 Codezeilen. Fügen Sie zum Beispiel über den Code-Blöcken eine Zeile hinzu, die beschreibt, was Sie tun:
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
Minimale Kommentare, die erklären, warum und was Sie tun, sind im gesamten Code sehr hilfreich. Ich bin mit der Antwort, die besagt, nicht einverstanden
Wenn ich auf Code stoße, der Kommentare enthält, bereite ich mich auf das Schlimmste vor: Der Code ist wahrscheinlich schlecht, und um ehrlich zu sein, sind die Kommentare wahrscheinlich auch schlecht.
Sehr oft wird anmutig guter Code dokumentiert. Es ist wahr, dass schlechte Programmierer ihre Dokumentation wie "Okay, mein Code ist schlecht, fügen wir ein paar Sätze hinzu, um es klarer zu machen" sehen.
Ja, und obwohl dies ziemlich häufig vorkommt, ist es auch richtig, dass gute Programmierer, die sauberen Code schreiben, sicherstellen möchten, dass sie zu ihrem Code zurückkehren und verstehen, warum sich ihre Funktion so verhalten soll oder warum sie das brauchten Leitung, die etwas redundant wirkt, etc ...
Ja, Kommentare, die offensichtliche Dinge erklären, Kommentare, die unklar sind, Kommentare, die nur zusammengestellt wurden, um sicherzustellen, dass "dieser Code dokumentiert ist, ja, was auch immer", Code-Geruch ist. Sie erschweren und irritieren das Lesen des Codes. (Ein Beispiel unten hinzufügen)
# Logging into Gmail when the module is imported
_client = login()
def get_client():
global _client
return _client
Beispielerklärung: "Keine Scheiße, Sherlock. _client = login()Meldet sich beim Mail-Dienst an? OMG!"
login()Zur Verdeutlichung: Die Methode hat keinen Bezug zur login()Methode aus dem obigen Beispiel.
Aber Kommentare, die den Standards entsprechen, das Warum und Nicht-Wie erklären und die richtigen Fragen beantworten , sind sehr, sehr, sehr hilfreich.
Inline-Kommentare
Eine Sache, die Sie NICHT tun sollten (und wenn ich das größer schreiben könnte, würde ich es tun), ist, Ihre Kommentare in die gleiche Codezeile zu schreiben. Es macht Kommentare sehr zeilenspezifisch, was den Zweck des Kommentierens Ihres Codes völlig verfehlt.
Zum Beispiel schlechte Inline-Kommentare:
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
Es wäre viel einfacher, diesen Code zu lesen und zu verstehen, ohne die Kommentare, die ihn unübersichtlich und unleserlich machen.
Stattdessen sollten Kommentare in Ihrem Code über den Codeblöcken platziert werden und die wichtigen Fragen beantworten, die beim Lesen des Codeblocks auftreten können.
# 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)
Viel klarer, oder? Jetzt wissen Sie auch, dass Sie die login()Funktion verwenden und die Parameter für send_mail()alles bereitstellen müssen, was Sie verwendet haben. Hilft ein bisschen, aber eins fehlt noch.
Funktionsdokumentation
Wurde viel diskutiert. Sie sollten Ihren Lesern immer mitteilen, worum es in Ihrer Funktion geht, warum und was sie tut. Wie es das macht, das gehört nicht zur Dokumentation, sondern vielleicht zu Fußnoten der Funktion.
Sie sollten klar beschreiben, was Sie von Ihren Parametern erwarten und ob sie mit einer bestimmten Methode abgerufen / erstellt werden sollen. Sie müssen angeben, was Ihre Funktion zurückgeben soll, wie sie verwendet wird usw.
Auch dies ist meine Meinung und Methodik beim Schreiben meines Codes. Nicht nur diese, sondern auch einige der Dinge, bei denen ich den anderen Antworten nicht zustimmen konnte. Oh, und natürlich lesen nicht nur die Kommentare Ihren Code aus, sondern auch Ihren Code selbst. Schreiben Sie sauberen Code, verständlich und wartbar . Denk beim Programmieren an dein zukünftiges Ich ;-)