Quali informazioni devono essere inserite nel blocco del documento a livello di file?

1

Principalmente sviluppo per Node.js. Ho preso l'abitudine di mettere un docblock a livello di file in tutti i miei file .js . Sembra qualcosa del genere:

/**
 * project-name
 *
 * Licensed under the BSD-3-Clause license
 * For full copyright and license information, please see the LICENSE file
 *
 * @author     Name <email>
 * @copyright  Year Name
 * @link       project-repository-url
 * @license    http://choosealicense.com/licenses/bsd-3-clause  BSD-3-Clause License
 */

// Code starts here...

Quando ho iniziato con Node.js, mi è sembrata una buona idea descrivere a quale progetto apparteneva il file, come era autorizzato e chi era l'autore. Prima di Node.js ho lavorato molto con PHP e alcuni strumenti di documentazione hanno persino raccomandato / richiesto tale docblock a livello di file.

Recentemente, però, ho iniziato a pensare che molte di queste informazioni siano ridondanti:

  • Le informazioni sulle licenze sono disponibili nel file LICENZA
  • Le informazioni sull'autore / copyright sono disponibili nel pacchetto.json / compositore.json / qualunque file
  • Il fatto che le informazioni sulla licenza siano nel file LICENCE è oggigiorno un fatto ben noto

E così mi rimane forse il nome del progetto. Poiché non mi piace la sensazione di rimuovere completamente il docblock a livello di file (sembra che manchi qualcosa), ti chiedo:

Quali informazioni (se presenti) dovrebbero essere inserite in docblock a livello di file?

Per rendere la domanda un po 'più reale di quella basata sull'opinione:

  • Qual è stata la motivazione / intenzione originale che le persone hanno iniziato a scrivere questi docblock a livello di file?

    I suspect this will be something along the lines "In the early 90s..."

  •   
  • In che modo questo intento si traduce nell'attuale ambiente di sviluppo software moderno? Qualcuno di questi intenti è ancora valido / ragionevole?
  •   
  • C'è qualche altra informazione che potrei considerare di aggiungere a un docblock a livello di file che non ho già lì?
  •   
posta Robert Rossmann 07.06.2015 - 23:31
fonte

1 risposta

1

La ripetizione di informazioni all'inizio di ogni file di codice sorgente rende IMHO sensato solo per ridurre al minimo il rischio di separazione della licenza e dell'amplificazione; informazioni sul copyright dal particolare file. Quindi, se tali informazioni sono già memorizzate altrove, il minimo assoluto da aggiungere è un riferimento al luogo in cui trovare tali informazioni. Se qualcuno ti invia un singolo file di codice sorgente come allegato di posta elettronica, il nome del progetto probabilmente non è sufficiente per scoprire quale licenza è in codice o dove trovare le informazioni sulla licenza. Quindi avere un suggerimento nel file del codice sorgente che è un file di licenza aggiuntivo ti dà la possibilità di chiedere alla persona che ti ha inviato la posta di aggiungere i file mancanti.

Se molte persone hanno accesso al codice sorgente, come nei progetti open source, più importante diventa impedire la separazione. E quando hai diversi contributori a un progetto, potrebbero esserci diversi diritti d'autore, diversi autori e condizioni di licenza individuali per i singoli file di codice sorgente. Per tali progetti, sembra ragionevole fornire un docblock più grande e standardizzato, con i segnaposto per tutte le informazioni che hai elencato sopra.

    
risposta data 08.06.2015 - 08:15
fonte

Leggi altre domande sui tag