Comments can help people see what the code is doing at a glance, without having to figure out what a particular function call is doing in the context where it’s being called. Sometimes, you’re just skimming, because you’re looking for something specific. Perhaps it helps you when searching for keywords? Here, I’ll include an example: Yesterday I wrote a little Godot mod loader, part of which is tweaking the project export to .zip up mods separately instead of including them in the main game.
# Ensure the output `mods/` directory exists.
DirAccess.make_dir_recursive_absolute(output_mods_path)
# Clear out old mods from the output `mods/` directory.
for name in DirAccess.get_files_at(output_mods_path):
DirAccess.remove_absolute(output_mods_path + "/" + name)
Now, admittedly, Godot’s naming of its built-in functions isn’t helping. But yeah, you can take a couple seconds to understand what the function call does, or you can read the comment and immediately have context for the code after it. I don’t think throwing these 3 lines into their own 2 extra functions would help anyone. Then again, maybe these are 50% “why” comments and 50% “what” comments.
On the other hand, here’s a larger comment that is needed to explain why that bit of code exists:
# Resources reference additional files that may be compressed or otherwise pre-processed,
# which are exported to `.godot/` instead of `mods/` and are listed in the `.import` file.
var import_file_path := file_path + ".import"
if FileAccess.file_exists(import_file_path):
var config := ConfigFile.new()
config.load(import_file_path)
for dep_file_path in config.get_value("deps", "dest_files", []):
_zip_file(zip, dep_file_path)
I understand that over-commenting things can be annoying, I understand that it’s good to encourage people to name symbols appropriately and to split things into functions that in some way act as good documentation on its own. But if you go too far, you end up with tons of methods that you have to jump around in the source code to figure things out, and that could pull you out of the flow too.
Commenting for the sake of commenting? No. AI slop comments? Heck no.
Commenting because it helps you internalize how something works, or helps you remember? Go for it! Commenting because you feel like it’ll help the next person understand your code? Please don’t shy away. I’d rather have a couple more unnecessary comments than too few with a spaghetti of nicely-named function calls.
Comments can help people see what the code is doing at a glance, without having to figure out what a particular function call is doing in the context where it’s being called. Sometimes, you’re just skimming, because you’re looking for something specific. Perhaps it helps you when searching for keywords? Here, I’ll include an example: Yesterday I wrote a little Godot mod loader, part of which is tweaking the project export to .zip up mods separately instead of including them in the main game.
Now, admittedly, Godot’s naming of its built-in functions isn’t helping. But yeah, you can take a couple seconds to understand what the function call does, or you can read the comment and immediately have context for the code after it. I don’t think throwing these 3 lines into their own 2 extra functions would help anyone. Then again, maybe these are 50% “why” comments and 50% “what” comments.
On the other hand, here’s a larger comment that is needed to explain why that bit of code exists:
I understand that over-commenting things can be annoying, I understand that it’s good to encourage people to name symbols appropriately and to split things into functions that in some way act as good documentation on its own. But if you go too far, you end up with tons of methods that you have to jump around in the source code to figure things out, and that could pull you out of the flow too.
Commenting for the sake of commenting? No. AI slop comments? Heck no.
Commenting because it helps you internalize how something works, or helps you remember? Go for it! Commenting because you feel like it’ll help the next person understand your code? Please don’t shy away. I’d rather have a couple more unnecessary comments than too few with a spaghetti of nicely-named function calls.