Devo ammettere di non essere d'accordo con alcune delle cose raccomandate dalle altre risposte, quindi lancerò i miei due centesimi;
Commenti
La documentazione è estremamente utile per gli estranei che leggono il tuo codice. Di solito molte cose non saranno abbastanza dettagliate per essere lette e comprese immediatamente, quindi dovresti spiegare cosa stai facendo.
Modifica : la discussione nella sezione dei commenti ha sottolineato qualcosa di giusto: i commenti eccessivi di solito vengono fatti quando si scrive codice errato .
Commentare il tuo lavoro dovrebbe essere preciso e minimale, ma, secondo me, dovrebbe assolutamente essere presente. Almeno un commento per ogni 15 righe di codice. Ad esempio, sopra i blocchi sul codice, aggiungi una riga su ciò che stai facendo:
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
I commenti minimi che spiegano perché e cosa stai facendo sono molto utili in tutto il codice. Non sono d'accordo con la risposta che afferma
Se mi imbatto in un codice contenente commenti, mi preparo al peggio: è probabile che il codice sia errato e, ad essere sincero, anche i commenti saranno probabilmente cattivi.
Molte volte, con garbo, è documentato un buon codice. È vero che i cattivi programmatori vedono la loro documentazione come "Va bene, il mio codice è cattivo, aggiungiamo alcune frasi per renderlo più chiaro".
Sì, e sebbene ciò si verifichi abbastanza, è anche vero che i bravi programmatori che scrivono codice pulito vogliono anche assicurarsi di tornare al loro codice e capire perché vogliono che la loro funzione si comporti in questo modo, o perché ne hanno bisogno linea che sembra un po 'ridondante, ecc ...
Sì, i commenti che spiegano cose ovvie, i commenti che non sono chiari, i commenti che sono stati messi insieme per assicurarsi che "questo codice sia documentato, sì, qualunque cosa", sono odori di codice. Rendono la lettura del codice più difficile e irritante. (Aggiunta di un esempio di seguito)
# Logging into Gmail when the module is imported
_client = login()
def get_client():
global _client
return _client
Chiarimento di esempio: "Nessuna merda, Sherlock. _client = login()Accede al servizio di posta? OMG!"
Ulteriori chiarimenti: il login()metodo non ha alcuna relazione con il login()metodo dell'esempio precedente.
Ma i commenti che corrispondono agli standard, spiegano il perché e non il come e rispondono alle domande giuste , sono molto ( molto ) utili.
Commenti incorporati
Una cosa che NON dovresti fare (e se potessi scriverlo più in grande, lo farei) è scrivere i tuoi commenti nella stessa riga del codice. Rende i commenti molto specifici per la riga, il che manca completamente allo scopo di commentare il tuo codice.
Ad esempio, commenti incorporati non validi:
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
Sarebbe molto più facile leggere e comprendere questo codice senza i commenti, che lo rendono disordinato e illeggibile.
Invece, i commenti all'interno del codice devono essere posizionati sopra i blocchi del codice e dovrebbero rispondere alle domande importanti che possono sorgere durante la lettura del blocco di codice.
# 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)
Molto più chiaro, vero? Ora sai anche che devi usare la login()funzione e fornire i parametri a send_mail()tutto ciò che hai usato. Aiuta un po ', ma manca ancora una cosa.
Documentazione delle funzioni
È stato ampiamente discusso. Dovresti sempre far sapere ai tuoi lettori di cosa tratta la tua funzione, perché e cosa fa. In che modo ciò non appartiene alla documentazione, ma forse alle note a piè di pagina della funzione.
Dovresti descrivere chiaramente quali sono i tuoi parametri e se desideri che siano ottenuti / creati in un metodo specifico. Dovresti dichiarare quale dovrebbe essere la tua funzione, a che serve, ecc.
Ancora una volta, questa è la mia opinione e metodologia durante la scrittura del mio codice. Non solo quelli, ma quelli sono solo alcune delle cose su cui non potrei essere d'accordo con le altre risposte. Oh, e ovviamente, non solo i commenti leggono il tuo codice, ma il tuo codice stesso. Scrivi codice pulito, comprensibile e gestibile . Pensa al tuo futuro io mentre scrivi il codice ;-)