I commenti sono considerati una forma di documentazione?

I commenti sono sicuramente documentazione. Per la maggior parte dei progetti, i commenti sono (sfortunatamente) la forma principale (se non solo) della documentazione del progetto. Per questo motivo, è molto importante farlo bene. È necessario assicurarsi che questa documentazione rimanga precisa nonostante le modifiche al codice. Questo è un problema comune con i commenti. Gli sviluppatori spesso li "sintonizzano" quando lavorano in codice familiare, quindi dimenticano di aggiornare i commenti per riflettere il codice. Questo può creare commenti non aggiornati e fuorvianti.

Molte persone suggeriscono di rendere il codice auto-documentante. Ciò significa che al posto dei commenti, puoi ristrutturare il tuo codice per rimuovere la necessità. Questo può sbarazzarsi della maggior parte dei commenti "cosa" e "come", ma in realtà non aiuta con i commenti "perché". Anche se questo potrebbe funzionare efficacemente per eliminare la maggior parte dei commenti, ci sono ancora molte volte in cui scrivere un commento è il modo più semplice ed efficace per documentare un pezzo di codice.

Sono una forma di documentazione, ma ricorda che la documentazione è negli occhi di chi guarda ....

• Per alcuni, codice di auto-documentazione è sufficiente. Ma ciò presuppone un livello di dettaglio tecnico come il cliente. Dovremmo stare attenti a pensare che questo è sufficiente, perché il nostro ego potrebbe dirci "È ovvio ciò che questo codice sta facendo", ma il tempo può dimostrare il contrario. Presuppone anche che tu sappia in anticipo le capacità del lettore.

• Per chi guarda il codice sorgente ma con meno competenze tecniche, commenti potrebbe essere ok. Ma questo presuppone che qualcuno stia guardando il codice sorgente.

• Se sei tecnico, ma non hai tempo per leggere tutto il codice sorgente, un manuale tecnico potrebbe essere ciò che è richiesto.

• Se l'utente non ha competenze tecniche, ma ha solo bisogno di sapere cosa sta succedendo, documentazione utente è ciò che è necessario.

Quindi la vera domanda è chi è il tuo cliente? Se lo sei, allora il codice o i commenti auto-documentanti sono sufficienti. Se è per qualcun altro, potresti voler ampliare la tua documentazione.

Sì, i commenti sono una forma di documentazione. Che siano o meno una documentazione utile per qualcuno che deve mantenere o aggiornare il tuo codice è una domanda aperta.

So che intendevi un esempio di esclusione, ma cose del tipo

print $foo; # this prints "bar"

non è utile; aggiunge solo confusione visiva. Non documentare l'ovvio.

Blocca i commenti all'inizio di una definizione di metodo o funzione che descriva la funzione o lo scopo del metodo (nei termini di alto livello ), input, output, valore restituito (se presente), eccezioni (se qualsiasi), le condizioni preliminari e le postcondizioni sono utili, ma solo nella misura in cui dicono a qualcuno come si suppone che la funzione o il metodo siano utilizzati. Non spiegano perché esiste la funzione.

Se qualcun altro ha bisogno di mantenere il proprio codice, è necessario documentare i requisiti e il progetto da qualche parte, e tipicamente non fatto nel codice sorgente stesso.

Trovo che attenersi all'approccio di Bob Martin a questo, da Clean Code, di solito risolve il problema se pensi di non commentare o di commentare e di lasciare fuori la documentazione:

We are authors. And one thing about authors is that they have readers. Indeed, authors are responsible for communicating well with their readers. The next time you write a line of code, remember you are an author, writing for readers who will judge your effort.

...the ratio of time spent reading vs. writing is well over 10:1. We are constantly reading old code as part of the effort to write new code.

Quindi, in altre parole, il tuo codice è auto-esplicativo senza la documentazione? Non esiste una regola per questo (a meno che non lavori per qualcuno come Microsoft la cui documentazione è pubblicamente accessibile), è soprattutto utile per aiutare il futuro lettore del codice che è spesso te.

La documentazione dovrebbe documentare Perché non il come . In che modo dovrebbe essere evidente nel codice, a meno che non si tratti di un trucco di ottimizzazione arcano o di un'altra tecnica specifica del linguaggio che non si verifica comunemente.

Il Perché probabilmente non dovrebbe essere nel codice, dovrebbe essere da qualche altra parte come un backlog di prodotto, legato ai commenti di commit con ID di storie che possono essere cercati in un log delle modifiche o in un nome di ramo .

I commenti sono una forma di documentazione. Una forma inferiore e una che suggerisce di aver individuato un'area del codice che può essere meglio trattata.

Sembra che tu commenta le cose in modo compulsivo. Avere altre opzioni può essere una buona cosa. Posso pensare a tre forme superiori di documentazione:

1) Calcola il tuo codice meglio. Invece di aggiungere un commento, estrai un metodo o una funzione il cui nome è il testo del commento che stavi per scrivere. Quindi il codice dice cosa stava per dire il tuo commento.

2) Test. Questa è la forma di documentazione che di solito cerco. Test unitari e test di accettazione sono documenti viventi e possono essere letti facilmente se per esprimere l'intenzione sono utilizzati molti metodi significativi, come nel punto 1.

3) Per gli script, l'opzione --help. Questo è dove si può diventare matti su doc. Adotta esempi, anticipa ciò di cui l'utente avrebbe bisogno.

In sintesi, se ti senti incline a inserire un commento, controlla se c'è un modo per comunicare al lettore strutturando meglio il codice. O c'è un test che comunica perché quel codice è lì? Se ti senti ancora incline a commentarlo, ammetti la sconfitta e fallo.