I primarily develop for Node.js. I got into a habit of putting a file-level docblock into all of my .js files. It looks something like this:
/**
* 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...
When I started with Node.js, this seemed like a good idea to describe what project the file belonged to, how it was licensed and who was the author. Before Node.js I worked a lot with PHP and some documentation tools even recommended/required such file-level docblock.
Recently, though, I started feeling like a lot of that information is redundant:
- Licensing information is available in the LICENSE file
- Authorship/copyright information is available in the package.json / composer.json / whatever file
- The fact that license information is in LICENSE file is nowadays a well-known fact
And so I am left with maybe the project's name. Since I do not like the feeling of completely removing the file-level docblock (it feels as if something is missing), I ask thee:
What information (if any) should go into file-level docblock?
To make the question a bit more factual than opinion-based:
- What was the original motivation/intent that people started writing these file-level docblocks?
I suspect this will be something along the lines "In the early 90s..."
- How does that intent translate into current modern software development environment? Are any of those intents still valid/reasonable?
- Is there any other information I might consider adding to a file-level docblock that I do not already have there?