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ì?