Desidero documentare il mio codice in modo tale che sia necessario leggere e sfogliare il codice almeno qualche mese dopo.
So che esistono diversi tipi di documentazione (nel codice sorgente e all'esterno, nei diagrammi di sequenza e così via).
Voglio solo sapere qual è un modo efficace per documentare il mio codice in modo che, quando alcuni mesi dopo voglio vedere il mio codice, dedico meno tempo alla lettura del codice e alla comprensione del flusso del codice.
Devo ammettere che non sono d'accordo con alcune delle cose che le altre risposte raccomandate, quindi ho intenzione di buttare i miei due centesimi;
La documentazione è estremamente utile per gli estranei che leggono il tuo codice. Di solito molte cose non saranno abbastanza prolisse da essere lette e comprese immediatamente, e dovresti quindi spiegare cosa stai facendo.
Modifica : la discussione nella sezione dei commenti ha messo in evidenza qualcosa di giusto: il sovradimensionamento viene solitamente fatto quando si scrive codice cattivo .
Commentare il tuo lavoro dovrebbe essere preciso e minimale, ma, a mio parere, dovrebbe essere sicuramente presente. Almeno un commento per ogni 15 righe di codice. Ad esempio, in cima ai 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
Commenti minimi che spiegano perché e che cosa stai facendo sono molto utili in tutto il codice. Non sono d'accordo con la risposta che afferma
If I come across code containing comments, I prepare for the worst: the code is likely to be bad, and to be honest the comments are likely to be bad too.
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 anche se questo si verifica parecchio, è anche vero che i bravi programmatori che scrivono codice pulito vogliono anche assicurarsi che ritornino al loro codice e capiscano perché vogliono che la loro funzione si comporti in quel modo, o perché hanno bisogno di quella linea che sembra un po 'ridondante, ecc ...
Sì, i commenti che spiegano le 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 odore 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
Example clarification: "No shit, Sherlock. does
_client = login()log into the mail service? OMG!"More clarification: the
login()method has no relation to thelogin()method from the above example.
Ma i commenti che corrispondono agli standard, spiegano il perché e non il come, e rispondono alle domande giuste , sono molto molto ( molto ) utili.
Una cosa dovresti NON (e se potessi scrivere quello più grande, lo farei), è scrivere i tuoi commenti nella stessa riga del codice. Rende i commenti molto specifici della linea, che manca completamente lo scopo di commentare il tuo codice.
Ad esempio, cattivi commenti in linea:
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 dovrebbero essere posizionati sopra i blocchi sul codice e dovrebbero rispondere alle importanti domande che potrebbero 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, giusto? Ora sai anche che devi usare la funzione login() e fornire i parametri a send_mail() con tutto ciò che hai usato. Aiuta un po ', ma manca ancora una cosa.
È stato ampiamente discusso. Dovresti sempre lasciare che i tuoi lettori sappiano di cosa tratta la tua funzione, perché e cosa fa. Come fa questo, questo non appartiene alla documentazione, ma forse alle note a piè di pagina della funzione.
Dovresti descrivere chiaramente cosa ti aspetti dai tuoi parametri e se vuoi che vengano ottenuti / creati in un metodo specifico. Dovresti dichiarare quale dovrebbe essere la tua funzione, quale sia il suo utilizzo, 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 che non sono d'accordo con le altre risposte. Oh, e naturalmente, non solo i commenti leggono il tuo codice, ma il tuo codice stesso. Scrivi codice pulito, comprensibile e gestibile . Pensa al tuo futuro se stesso durante la codifica; -)
IMO la migliore documentazione è la documentazione di cui non hai effettivamente bisogno. Odio anche scrivere documentazione e commenti.
Detto questo:
n , ma numberOfItemsFound per esempio. Tratta il tuo codice come documentazione
Il tuo codice è la tua documentazione principale. Descrive con precisione cosa fa l'app, la libreria o qualsiasi altra applicazione. In quanto tale, qualsiasi tentativo di accelerare la comprensione di quel codice deve iniziare con il codice stesso.
Ci sono molti scritti su come scrivere codice leggibile, ma alcuni dei punti chiave sono:
n è buono per un ciclo, nomi descrittivi più lunghi sono necessari per gli oggetti con un ambito maggiore), UpdtTbl con un commento che spiega che aggiorna la tabella con le regole fornite quando UpdateTableContentsWithSuppliedRules può essere usato come nome, Diventa migliore leggendo il codice
Il codice di lettura, indipendentemente da quanto sia semplice, è un'abilità acquisita. Nessuno è naturalmente bravo a leggere il codice. Ci vuole pratica; molta pratica Quindi, per esempio, vai su Github o qualsiasi altra cosa e leggi il codice delle librerie che usi, piuttosto che usare semplicemente quelle librerie. Trova il codice per leggerlo e leggerlo.
I commenti sono un odore di codice
Solo così arriviamo ad altri tipi di documentazione. In primo luogo, come precedentemente affermato, evitare commenti. Se mi imbatto in codice che contiene commenti, mi preparo per il peggio: il codice è probabile che sia cattivo, e ad essere sincero anche i commenti potrebbero essere cattivi. È improbabile che qualcuno che non riesce a comunicare bene attraverso il codice sia in grado di comunicare meglio attraverso il linguaggio naturale.
Attenzione alla documentazione delle API autogenerate
Inoltre, fai attenzione alla documentazione API autogenerata. Se devo ricorrere alla lettura di tali documenti, sarà perché il tuo codice è così difficile da leggere. Di nuovo, rendi il codice semplice e posso leggerlo direttamente.
Anche i test sono documenti
I test sono anche documentazione. Quindi non trattare i tuoi test unitari come un lavoro ingrato. Trattali come un modo di comunicare con gli altri (il tuo sé successivo di sei mesi è incluso qui) su come funziona il codice e deve essere usato.
Disegna le immagini se aiuta
Se ti piace UML, allora troverai sicuramente un buon strumento e generi diagrammi UML dal tuo codice. Solo mai e poi mai e poi mai provare a usarlo per generare codice. Non è buono come strumento di progettazione e di conseguenza si otterrà un codice orribile.
Hai un documento di visualizzazione "1000ft"
Infine, scrivi te stesso un documento di panoramica. Cosa fa l'app? Come lo fa? A quali altri sistemi si connette? Cose del genere. Non tentare di descrivere la struttura del codice qui però. Lascia che sia il codice a farlo. Lascia che questo documento ti ricordi perché hai scritto il codice in primo luogo.
A meno che tu non abbia un dominio molto tecnico, la maggior parte delle domande sul codice non riguarderanno il "come" ma il "perché" o il "cosa".
In quanto tale, il modo per ridurre le persone dal dover cercare nel codice, è di scrivere una breve descrizione di esso. Il vantaggio di questo è che puoi compilare una panoramica delle descrizioni abbastanza facilmente, e che questo è molto più accessibile. (Anche a persone che non hanno / non sono autorizzati a vedere il codice).
Anche se le persone sono tecniche, la lettera di presentazione dovrebbe offrire indicazioni su dove dovrebbero cercare qualcosa.
Semplici punti estremamente minimalisti:
Il maggior guadagno di velocità che ottengo solitamente dalla costruzione di commit separati che rappresentano ciascuno un passaggio intermedio che compila e funziona.
Quindi, se devo introdurre un nuovo parametro in una funzione per implementare una funzione specifica, esiste un commit che non fa altro che aggiungere il parametro nella dichiarazione, nella definizione e in tutti i siti di chiamata. Quindi, il prossimo commit introduce funzionalità, mentre il terzo aggiorna i siti di chiamata che utilizzano la nuova funzionalità.
È facile da recensire, perché le modifiche puramente meccaniche possono essere guardate rapidamente e poi togliersi di mezzo.
Allo stesso modo, se si riformatta il codice, questo dovrebbe sempre essere un commit separato.
Anche se ci sono uno o due punti di disaccordo apparenti tra le risposte esistenti, se solo in enfasi, cercherò di riassumere il solito consiglio in un modo che chiarisca da dove provengono tutti:
D'altra parte, se mai dovrei sbagliare troppo troppo nell'altro senso, quasi mai usando commenti. I revisori del codice ti faranno sapere se hai l'equilibrio nel posto sbagliato per loro, ma se fai uno sforzo consapevole per seguire il piano in 3 punti sopra, probabilmente sarai comunque vicino al loro optimum.
Leggi altre domande sui tag code-reviews documentation help-documentation documentation-generation
