As the title says - should you comment and/or document code?
How to (not) do it properly?
What best practices do you stand by when commenting/documenting your code?
I moved the discussion from Game design document to keep the original topic clean.
I know I should fully comment code, but it normally lies in the pile of good intentions, which also contains my promise to take 10000 steps daily. 
Itâs a controversial topic, but I believe you shouldnât. Your code should be readable and self explanatory, through proper variable naming etc. and commented exceptionally only if the logic is not obvious from reading the code.
Hereâs a good and short video about it:
Different story if youâre designing something like a Plugin that will be public and used by other people - then proper documentation of code is relevant, but only for the external APIs through which users interact with your Plugin.
5 Likes
Ok, so I agree with @wchc, and I like the video, but I think thereâs a piece of the video that should be highlighted - Code Documentation. First, code should be self-documenting which the first part of the video handles. I just went into great detail in this thread here about that: Modular Character Controller (v4.4-4.6) - #21 by dragonforge-dev Since I spent like 2 hours writing that post, Iâm going to recommend you read that instead of trying to re-iterate it here in detail. The short version is that naming things appropriately makes comments (largely) unnecessary.
However, you are using Godot. Which means that every public function and variable you create should have documentation. (A function or variable is private if it starts with an underscore, public if not.) There are a few reasons for this.
First, Godot will create a Documentation page for you.
This is an example of the documentation for my custom State class, automatically generated by Godot for me, and everyone who uses my State Machine Plugin. Now, as @wchc pointed out, this is essential for plugins, but I believe itâs a good habit to get into anyway. (More on that in a bit.)
Second, for functions, it provides context-sensitive pop-up help when you hover over a documented function name.
Third, for @export variables it allows you to hover over the value and see the comments in the Inspector.
Fourth, for public variables it allows you to hover over the value in code and see the comments.
Finally, itâs a good habit to document your code because there is always someone using your code after you who needs to know what you were thinking when you made a decision. 90% of the time, that person is future you who is no longer steeped in the problem and cannot remember the decisions you made to get to that point. If your code is self**-documenting**, and your public functions and variables are documented - you will spend a lot less time saying, âWhat was I thinking here?â
Usually people figure this out after re-writing something that looked insane previously, and then realizing they broke the code and having to revert back to the insane code.
Keep in mind that comments in GDScript start with one pound sign (#) and documentation start with two pound signs (##).
## This documentation will show up in the editor.
## A value greater than 1.0 makes the player jump slower and for less height.
## [br]A value less than one makes the character jump faster and higher.
@export var jump_gravity_multiplier: float = 1.0 # This comment will not but I want to remind myself of why I defaulted to 1.0 so I don't try to change it later when I look at this code.
4 Likes
Good points and well put! Thanks @dragonforge-dev for the read!
While I agree with the sentiment and would not discourage anyone from doing that if they prefer it this way, I wouldnât necessarily actively promote it myself either. I rarely document functions and variables in my projects, because:
- It is redundant in most cases as itâs usually mostly obvious from the context. E.g. there is no added value in documenting what
var max_speed: floatis, itâd just add bloat. - Itâs not fun. Iâd guess people in this community are doing gamedev mostly for fun, so documenting would be an additional chore, which might discourage someone from gamedeving.
My take is just that itâs ok not to document your code, if youâre willing to live with the (I believe minor) consequences of that choice, e.g. as you mentioned - coming back later to the project after months and not understanding what some part of the code does.
I feel like a lot of beginners heard that they should document the code and they need to do it, otherwise they wonât succeed. Thatâs not true, itâs ok not to do it.
I stand by Pareto principle, which says that, on average, 80% of effect is achieved with just 20% of effort. Translating this to this subject - by just sticking to proper naming conventions, self-documenting code and sporadically documenting a couple of more complex functions and variables, youâve already achieved the 80% of the effect, thereâs no need to go the extra mile to get to a 100%.
All of course depends on the context, so we can probably argue all night long and wonât find an objectively correct truth. Itâs fun to discuss the differences in approach nonetheless 
4 Likes
Personal experience but Iâve been taught that you should document code, not comment it.
Good code should explain itself and what it does. If you need to include a bunch of comments, you are likely doing something wrong, and youâll have trouble in the future as your game / application grows in size.
That being said, some comments are good, and especially JSDoc comments can benefit you immensely. To explain what a function does briefly, that will also appear as tooltips in a lot of IDEs when you are writing your code.
What you should not do imo, is what most LLMs do, where they will put a comment on almost every single line to explain it, even if itâs super obvious.
At which point it just becomes silly, like:
# This will set the value 10 to the variable called speed
speed = 10
Please donât do that, it genuinely makes the code harder to read.
3 Likes
Fun fact: Godot source code is very sparsely commented.
4 Likes
I agree with that. If you look at all the variable declarations in my code (from the example above) you will see I only documented the really weird thing, as everything else is self-explanatory:
const JUMP_BUFFER_TIME = 0.05
const COYOTE_TIME = 0.15
@export var jump_velocity: float = 400.0
## A value greater than 1.0 makes the player jump slower and for less height.
## [br]A value less than one makes the character jump faster and higher.
@export var jump_gravity_multiplier: float = 1.0
var jump_buffer_timer: float = 0.0
var coyote_timer: float = 0.0
@onready var jump_sound: AudioStreamPlayer = $"Jump Sound"
In this case the documentation is so I donât have to dig into how the variable is used to remember if I want it greater or smaller than 1.0 when tweaking it in the editor.
NOTE: If youâre curious, the reason jump_buffer_timer and coyote_timer are float and not Timer objects is because Timer objects are not reliably precise at less than 0.5 second. And both of them run for less time than that.
1 Like
Commenting weirdness is typically most useful. Here are couple of comments I encountered the other day when refactoring some of my old code. They are even in caps.
// NOT WORKING PROPERLY - REWORK
// DUBIOUS - CHECK THIS SECTION, DETERMINE WHAT IT DOES AND CLEAN UP
I particularly love the âdetermine what it doesâ part 
7 Likes
I typically add âTODO:â in my comments like that, as a lot of language will parse those out.
# TODO: Add unit tests.
# TODO: Figure out why I did this here.
4 Likes
You might like this plugin then. It turns your comments into actionable items. For your own sanity, donât look at the source code, itâs ridiculous. I have it on my TODO to rewrite it completely and either submit a PR there, or publish it separately. But the idea is very nice.
2 Likes
Yeah, thatâs a funny one 
1 Like
I agree with what appears to be the consensus here: comments bad, documentation ok.
As otherâs have said, the code should document itself. However I have yet to see the best argument against them put forward, which is that they very easily get out of sync with the code. Maybe not entirely relevant here, where we are mostly solo devs, but if you go out and work in the âreal worldâ on big codebases you quickly learn to ignore comments and trust only the code.
Hilariously, Iâve been challenged in code reviews for deleting comments that were clearly bs; so the views put forward here are by no means universal, apparently there are people out there who think any comment is better than none.
3 Likes
A bit of context,just for fun Iâm making a networking lib in c++ and this is the doc after covering introduction and few functions:
# Just Like this,Read through the code and you'll understand it,noo need to read a doc!
## Now I understand why Dear ImGui got that bad and poo poo doc.
Info:It works smooth as heaven! I canât believe I made it
Even tho I tried to make a p2p one but my NAT is a son of a warden,itâs soo strict : (
Well,I can make my own site with it and can do a little LAN party : D
1 Like
This was mentioned in the video that @wchc posted.
I agree that they get out of date, but in a professional setting I am high enough up the food chain that I just reject any PR that has bad documentation. That problem only happens once. When people know that it matters, they do it. Then they rely on it being good in that project. Documentation, not comments.
The reason that I try to document things is so that people will understand what Iâve done after Iâm gone - and so that theyâll adopt what Iâm doing and contribute. My State Machine Plugin is a Godot example of that. I made it for me. I documented it for future me. I hoped that maybe someone else would contribute to the repo at some point, and @wchc has.
As @wchc has pointed out, my own projects are not as militantly documented. But that again depends on A) if I am collaborating (or making a paid project that someone else is going to take over), and B) if Iâm doing something quick like a game jam, vs. something I am going to re-use (like a plugin.)
Iâve found that documentation, unit tests, and regression tests get out of date when they are not a part of the pipeline. When they are a part of the pipeline and being used - they stay up to date.
4 Likes
No more
#Now,Only god knows it!
moment
2 Likes
Iâve literally run into this multiple times professionally. More than once Iâve been able to just delete huge swaths of code like this and no one has even noticed for months or even years that the feature is gone.
1 Like
All good points, my argument was aimed squarely at inline comments, not doxygen style documentation for classes/functions.
2 Likes
Just document code you intend for others to use. If itâs a library or framework thatâs a must. Do document odd things (i.e.: workaround for framework bug). Add TODOs whenever needed. Furthermore, documenting stable more advanced design with something like https://plantuml.com/ is always helpful.