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!

  • 3
    The DRY principle applies to comments as well.
    – Doc Brown
    Mar 31, 2021 at 9:58
  • @DocBrown Interesting, I didn't know that. Thanks for the information
    – Junes
    Mar 31, 2021 at 10:02
  • 1
    This is not a question of knowledge, but common sense - when you duplicate something in your code (and comments are code as well) which should always be the same, you produce a source of maintenance issues, I hope this is obvious. Placing the repetitive parts in a single "readme" or "docs" or "copyright" file avoids these issues.
    – Doc Brown
    Mar 31, 2021 at 10:17
  • @DocBrown, I agree with you, except for the copyright information. The copyright line and (a pointer to) the license should be repeated in every single file to ensure this legal information doesn't get lost if a file gets separated from the rest of the repository. Mar 31, 2021 at 11:13
  • 5
    The only people who endorse vertical lines after comments are those who’ve never had to edit those comments. Avoid choices that harm flexibility. Mar 31, 2021 at 12:18

4 Answers 4


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.

  • Yeah I read about that comment should answer "Why" and not "What" questions, although this approach seems like a better idea. I'd imagine though that it might get messy if you do this for every method, so is it better to use it just for every class? What's the "rule" here?
    – Junes
    Mar 31, 2021 at 10:05
  • The rule is what you want it to be! But generally if something is a "public" API that's expected to be used outside your team, per-method documentation is a good idea. For internal use it only has value if it contains non-obvious information.
    – pjc50
    Mar 31, 2021 at 10:16
  • @Junes Apart from your preferences context also plays a role. In a dynamically typed language where the types cannot reasonably be part of the function signature putting them into a comment like in this answer is great. But in a statically typed language where the types are an integral part of the function signature repeating them in a comment is useless and annoying to maintain.
    – besc
    Mar 31, 2021 at 18:23

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.

  • Yeah those are logical reasons... I should stick with the given tools and optimize it instead of trying to use "workarounds" that aren't really being needed. Thanks for your answer
    – Junes
    Mar 31, 2021 at 12:07
  • Very good answer. The only thing it is missing, in my opinion, is that the "Title" in the comments should not be needed either. The file name, or the name of a Type defined inside the file should be good enough for a title. No need to repeat that either. Mar 31, 2021 at 15:25
  • The "Notes" section might be better off as inline comments near the code the notes pertain to. And there again, the "notes" should explain the "why" not "how" or "what". Mar 31, 2021 at 15:26

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.

  • I definetly get that software is constantly changing, and although the changes might not be huge at first sight, they might add up and the code ends up decently different from the "original" version, Also unless my company requires a "copyright header", I'm not going to implement the comment section at the top. Thanks for your answer!
    – Junes
    Mar 31, 2021 at 11:37

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.