I commenti sono considerati una forma di documentazione?

Quando scrivo piccoli script per me stesso, impilo il mio codice in alto con commenti (a volte commento più di quanto codice). Molte persone con cui parlo affermano che dovrei documentare questi script, anche se sono personali, in modo che se mai li vendessi, sarei pronto. Ma i commenti non sono una forma di documentazione?

Non sarebbe questo:

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

essere considerato documentazione, soprattutto se uno sviluppatore sta usando il mio codice? O la documentazione è considerata al di fuori del codice stesso?

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

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

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

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

• Per coloro che guardano il codice sorgente ma con meno esperienza tecnica, i commenti potrebbero essere ok. Ma questo presuppone che qualcuno stia guardando il codice sorgente.

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

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

Quindi la vera domanda è chi è il tuo cliente? In tal caso, è sufficiente un codice o commenti auto-documentanti. Se è per qualcun altro, potresti voler ampliare il modo in cui documenti.

Sì, i commenti sono una forma di documentazione. Se sono o meno utili documenti per qualcuno che deve mantenere o aggiornare il codice è una domanda aperta.

So che lo intendevi come esempio usa e getta, ma cose del genere

print $foo; # this prints "bar"

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

Bloccare i commenti alla testa di un metodo o di una definizione di funzione che descrivono la funzione o lo scopo del metodo (in termini di alto livello ), sono utili input, output, valore di ritorno (se presente), eccezioni (se presenti), condizioni preliminari e postcondizioni, ma solo nella misura in cui dicono a qualcuno come dovrebbe essere usata la funzione o il metodo. Non spiegano perché esiste la funzione.

Se qualcun altro ha bisogno di mantenere il tuo codice, devi documentare i requisiti e la progettazione da qualche parte, e questo in genere non è fatto nel codice sorgente stesso.

Trovo che attenersi all'approccio di Bob Martin a questo, da Clean Code, di solito risolva il problema se pensi che stai commentando o commentando e tralasciando la documentazione:

Siamo autori. E una cosa sugli autori è che hanno lettori. In effetti, gli autori sono responsabili di comunicare bene con i loro lettori. La prossima volta che scrivi una riga di codice, ricorda che sei un autore, che scrive per i lettori che giudicheranno i tuoi sforzi.

... il rapporto tra il tempo dedicato alla lettura e la scrittura supera di 10: 1. Leggiamo costantemente il vecchio codice come parte dello sforzo di scrivere nuovo codice.

Quindi, in altre parole, il tuo codice è autoesplicativo senza la documentazione? Non ci sono regole stabilite per questo (a meno che tu non lavori per qualcuno come Microsoft la cui documentazione è pubblicamente accessibile), dipende principalmente dall'aiutare il futuro lettore del codice che spesso sei tu.

La documentazione dovrebbe documentare il Why not the How . Il Come dovrebbe essere evidente nel codice, a meno che non si tratti di un trucco di ottimizzazione arcana 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, che è legato a commettere commenti con ID di storia che può essere cercato in un registro delle modifiche o il nome del ramo.

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

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

1) Fattorizza meglio il tuo codice. 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. I test unitari e i test di accettazione sono una documentazione vivente e possono leggere facilmente se vengono utilizzati molti metodi significativi per esprimere l'intenzione, come al punto 1.

3) Per gli script, l'opzione --help. Qui è dove puoi impazzire sul doc. Attenersi agli esempi, anticipare ciò di cui l'utente avrebbe bisogno.

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