0

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!

6
  • 2
    The DRY principle applies to comments as well.
    – Doc Brown
    Mar 31 at 9:58
  • @DocBrown Interesting, I didn't know that. Thanks for the information
    – Junes
    Mar 31 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 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 at 11:13
  • 1
    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 at 12:18
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.

3
  • 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 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 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 at 18:23
3

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.

3
  • 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 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 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 at 15:26
0

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.

1
  • 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 at 11:37

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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