Qual è il termine corretto per la documentazione che abbiamo inserito appena sopra una dichiarazione del metodo?

Question

Sto scrivendo un white paper e ho capito che non sono sicuro di quale sia il termine ufficiale per il tipo di documentazione interna che mettiamo come blocco di commenti prima di una dichiarazione di definizione.

La stessa cosa che alla fine diventa la documentazione per i membri JavaDoc.

Non si tratta semplicemente di documentazione interna e non sono sicuro " header header " sarebbe un buon termine.

Nota che sto cercando un termine generale, non uno specifico per una lingua particolare (ad esempio Java / Perl)

Answer 1

Questa è chiamata specifica del metodo o specifica della procedura . Cioè, specifica il comportamento della procedura piuttosto che i dettagli di implementazione. Alcuni libri di testo si riferiscono ad esso come al contratto del metodo, ma potrebbe essere un po 'ambiguo.

Answer 2

Nella mia organizzazione lo chiamiamo metodo o funzione doc-comment. La documentazione a livello di funzione è probabilmente il termine più utilizzato.

Answer 3

Lo chiamo sempre commento di metodo (o funzione), per distinguerlo dai commenti di classe o file.

Answer 4

Viene spesso definita professionalmente come una "clausola sui requisiti" o una "clausola assicurativa".

Answer 5

Di solito mi riferisco ad esso come "documentazione in linea". Per me è di questo che si tratta: il fatto che la tua documentazione sia in il tuo codice sorgente, quindi c'è più possibilità che i documenti rimangano sincronizzati con il codice.

(Questa non è una garanzia, ovviamente, ma incoraggia i programmatori a mangiare le loro verdure. Significa che lo sviluppatore può cambiare la documentazione contemporaneamente e nello stesso posto il comportamento cambia, piuttosto che dopo il fatto e in un altro posto.)

Answer 6

Lo chiamo commenti in codice, così semplice.