Is it good practice to put comment headers into each file?

Question

I have an Unity project with countless of C# script files and I'm working on it solely.

Although nobody else is working on it, I'm aware that some form of code documentation is crucial for my future self.

What I thought about is putting comment files like these into each file / class at the top for a better overview:

/*-------------------------------------------------------------------------------\
| Title                                                                          |
+--------------------------------------------------------------------------------+
| Repository:                                                                    |                                                                       
| 2021 (C) Company                                                               |
+--------------------------------------------------------------------------------+
| This module was programmed by XYZ                                              |
+--------------------------------------------------------------------------------|
| Version 1.0                                                                    |
+--------------------------------------------------------------------------------+
| CODE DESCRIPTION                                                               |
| ________________                                                               |
|                                                                                |
+--------------------------------------------------------------------------------+
| NOTES                                                                          |
| _____                                                                          |
|                                                                                |
\-------------------------------------------------------------------------------*/

I've read some counter-arguments to this. For example, code might change and I would have to update my code description in the comment at the top.

Now, what if I have my engine already set to go and I'm sure that there's not gonna be any more major changes to it? And even if I had to make changes, I would remind myself of updating the header comment, too.

Would you say that this is bad practice? And if so, why? And what else would be your suggestion for documenting game project/Unity stuff properly?

Thanks in advance!

Answer 1

A bloated ascii-arty comment header in each file is not a good idea.

Decorating public constructs (public interfaces, classes, methods) with summaries and parameter information is a lot more helpful.

/// <summary>
/// Calculates the sum of two numbers.
/// </summary>
/// <param name="a">The first non-negative integer to be used in the sum.</param>
/// <param name="b">The second non-negative integer to be used in the sum.</param>
/// <returns>A 32-bit positive integer, representing the sum of the two specified numbers.</returns>

But more importantly: write clean, self-documenting code that doesn't need so many comments.

Answer 2

I don't have a strong opinion on adding a company name and license into the code, however I can share my opinion on the rest of the things.

Author - Should be tracked by versioning system like Git or SVN.

Version - Library should have a version, product should have a version, but not the individual class. Version is by default managed by versioning system, adding anything on top of that gives you a lot of work with very little gain.

Code Description - Comments are a bad concept, we just don't have anything better. They are a workaround to a problem, that code is not self-descriptive. They summarize or copy the code, they have to be written, they tend to get outdated. Use them to summarize the responsibility of the class if it is not obvious or use them to describe an API, this may be helpful, but rather make a class/method/variable name 50 characters long than writing a comment.

For the more complicated stuff, like some architectural concepts, that are not obvious from the code I like to use the Markdown files.

Notes - This seems to me like comments of comments, I wouldn't use this either.

Answer 3

Now, what if I have my engine already set to go and I'm sure that there's not gonna be any more major changes to it?

This never happens.

All software is either "dead" or subject to a constant drip of change pressure. Granted, in older systems you can go years without touching a file, and major architectural changes are usually hard after the initial buildout phase, but the one constant of software is that it changes.

Having said that, in most professional environments there's a copyright header with the year and company name. It's not required for copyright law but it makes it explicit who owns it.

A mention of the license can be useful. One sentence, not the whole license.

There is usually a short description of the purpose of the code in the file. Short, usually a sentence or two. If you want to have a long discussion of the architecture that may be better off done separately.

Individual "author" and "version": used to be popular, probably based on traditional document preparation practice, but modern version control makes this obsolete. "git blame" will tell you who wrote what.

Answer 4

A minimalist header is a useful practice:

• A title does not harm; it provides some human context at little expense

• The copyright notice is recommended for practical reasons related to intellectual property laws. These are country-dependent but in the US, for example the notice shall:

  (...) be affixed to the copies in such manner and location as to give reasonable notice of the claim of copyright.

  The header is obviously a place that meets the requirements. Also, the formal registration process requires to deposit a printout or a PDF) with the first and the last 25 pages of the "source code" (less in case of trade secrets). Having the notice in very file ensure that however the printout is produced, the copyright will always be in a visible place.

  Last but not least, individual files can be copied/cloned with no link to the original repository and LICENCE file. Not having the copyright in the source file might be an issue in case of litigation.

Some elements depend on the context:

• A repository or a filename is not necessary. It can nevertheless be useful, especially in languages that do not have build-in support for packages or modules.

• Author is a particular beast. While author ids can be found in source control, sometimes a new source control system is chosen and the history is lost. Moreover there can be a legal aspect to this: in many countries there is a difference between the patrimonial rights (the ownership by the company) and the moral rights (of the real authors, having possibly the right of their name associated with their work). For this reason, a section "Authors", close to the copyright notice, with a simple list of contributors could make sense.

You can definitely remove:

• The nice framing: the alignement effort is really not worth it.

• Version and comments: they are better followed in source control (commit id and commit comment). This will btw avoid the confusion between the software version and the file version.