Perché i commenti / documentazione di una funzione JavaScript dovrebbero includere così tanto? [duplicare]

Naviga le tue risposte
10

Stavo studiando le pratiche di commento appropriate per JavaScript e la risposta con una buona spinta (+100) cita i commenti di tipo JSDoc. JSDoc promuove commenti come questo: 

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
}

Da quanto ho capito, i commenti positivi dovrebbero spiegare "perché" non "cosa" e quanto sopra sembra un sacco di "cosa" per me.

Perché JavaScript dovrebbe essere commentato / documentato in questo modo, e in che modo questo si riferisce alla popolare politica di commento "perché, non come"?

    
posta Viziionary 19.09.2015 - 01:23
fonte

4 risposte

15

Il pubblico di destinazione per i commenti interni è il gestore del codice. I manutentori del codice dovrebbero essere in grado di dire "cosa" dal codice stesso.

Il pubblico di destinazione per i commenti esterni è il consumatore del codice. Ai consumatori di codice non interessa il "perché", dal momento che stanno usando il codice, non modificandolo. Pertanto, i commenti esterni tendono a rispondere "cosa". I consumatori di codice necessitano di una documentazione molto esplicita, dal momento che devono capire a quale funzione chiamare, non come funzionano quelle funzioni.

    
risposta data 19.09.2015 - 01:42
fonte
18

Questo non è un commento. È la documentazione, che, poiché ECMAScript non supporta la documentazione come lingua, è scritta all'interno di un commento.

Si noti che i "commenti di documentazione" come questo sono fondamentalmente diversi dai commenti "normali": i commenti vengono ignorati dal parser, non raggiungono nemmeno le fasi successive del compilatore / interprete. Sono essenzialmente spazi bianchi.

Tuttavia, i commenti della documentazione sono elaborati. Non vengono elaborati dal compilatore / interprete, ma sono elaborati dall'IDE o dagli analizzatori statici. (E ovviamente anche i generatori di documentazione.)

    
risposta data 19.09.2015 - 03:17
fonte
8

JSDoc è inteso per generare documentazione che viene letta separatamente dal codice. Anche se il codice è auto-documentante, non aiuterà il lettore della documentazione generata, perché potrebbe o meno avere accesso al codice.

    
risposta data 19.09.2015 - 01:42
fonte
1

Oltre alle altre risposte, è utile anche per gli IDE che possono aiutare con le funzionalità di completamento del codice dai file di origine o di libreria. Questo è vero per qualsiasi lingua però.

    
risposta data 19.09.2015 - 06:35
fonte

Leggi altre domande sui tag

Le storie degli utenti sono troppo di alto livello e concettuali, la gestione si aspetta che gli sviluppatori riempiano gli spazi vuoti Design Patterns: dovrei impararli? [chiuso]