Should you comment and/or document code?

Commenting a section is better than extracting it into a function if the section is not reusable. Better to leave the code where it’s needed than to put it somewhere else.

2 Likes

I have to disagree. It makes the section easier to test. The function is not necessary for re-use. It also makes reading the code surrounding the only usage easier too read and reason about.

Here’s my take: as someone once said, writing code is easy, reading code is hard. But that’s the part that really matters. Make a code easy to read, and it will be easy to maintain. Fail to do it, and you will struggle

Of course, this is easier said than done. Comments, in my opinion, are one of the tools that helps here. It’s not a silver bullet, of course, and, like any tool, using them wrongly can also do more harm than good. But use them wisely, and they can be indispensable.

So when and how to use comments? My rule of thumb is - when you can’t make the code obvious enough that you can do without them. Sometimes that happens. Especially in game development where you might need some non-trivial algorithms. Then you should add comments to explain what the code does.

Maybe with one level of depth. If you start consistently applying your principle of functionalizing non-reusable sections then functions you already put away may themselves get extractions that are also put away and so on, chopping your naturally linear code into ever smaller parts that are scattered all over the place. Chasing bugs in scattered code is much more mentally taxing than in linear code.

I never understood this phobia of long linear sections of code. Sounds like something from Uncle Bob’s playbook of fictional code cleanliness. If the code does a long linear sequence - let it be just that. You can fold in most editors if looking at long sections of code confuses you. Navigation shouldn’t be done visually anyway, you’ll get lost sooner or later. Always use searching and refactoring functionality of your editor/ide. And if you navigate visually, it’s better to have natural sequences appear as sequences and not as jumps.

3 Likes

Godot doesn’t have refactoring. The closest you can get is find and replace in all files:

Ctrl + Shift + R

1 Like

It’s not a phobia about long sections. As I mentioned in my first answer: the moment you need a comment, the long section might be too long. Let me give you another view why I recommend extracting functions at comments (or other logical points in the code)

Extracting functions after a while will provide room for two things

Experimentation: Especially in game development this is welcome. Create a variant of a function foo() like foo_with_lasers() without editing a long section like commenting out one variant or adding another variable, if etc. pp.

Debugging: I find debugging easier as with every function call I can decide to step in or step. The stack frame is smaller. I can exempt the function of the bug hunt and have less to keep in mind.

But your mileage may vary.

2 Likes

That’s what version control is for.

Didn’t the OP started this topic about commenting or documenting code?

Why you guys are at version control?

I have no idea :smile:

Now it downed on me that we forgot to mention that comments are very useful for commenting out the code.

3 Likes

My last statement:

You do both :crossed_fingers:

See ya!

1 Like

I document almost everything i end up parsing or interpreting to use.
On my own code, even some of the private methods end up documented just in case someone wants to reuse some part of it.
I constantly spend these extra 5 minutes on each method so that it won’t cost me another 50 when i forgot what some function does and end up Ctrl + LMB - ing into no-man’s land (usually wastelanded by yours truly)

1 Like

I am faster with logic, slower with language, i couldnt comment every line if i was getting a dollar per word. I find it to be a waste of time if i can read the code clearly.

[this discussion that i missed by several months] It’s aliiiiiiiiiiiiiiiiiiiiiive!

2 Likes

Code as overtaken my brain’s normal function.

For me as long as it helps you - it’s good practice, really, many say that comments are bad cuz variables should name themselves ect. but it’s very broad - you don’t have single Yes/No, but rather thousand small situations where there’s a decision

If you’re still bothered with this kind of question, just try out code with and without comments and see what helped you more, never be afraid to experiment

1 Like

Hello!
I find commenting code helpful, because I am slow at reading code and math. I personally use comments in four main ways (number 2. is the only one that hasn’t been mentioned yet).

  1. I use comments primarily to remind myself how certain things are handled. Example:
...
match card_stats.Speed:
	CardStats.SPEED.QUICK: # Play card, no enemy response.
		player_action(card, target)

	CardStats.SPEED.STATUS: # Play card first, then enemy response.
		player_action(card, target)
		enemy_turn(target) 

	CardStats.SPEED.SLOW: # Enemy turn first, then play card.
		enemy_turn(target)
		player_action(card, target)
...
  1. I use comments to remind myself how math works. Example:
...
# If we only have one card, deck offset should be zero, so yes, decrease card amount by one
var deck_offset: float = card_width * (card_amount - 1)
...
  1. I use comments to remind myself what to add and where:
...
# TODO Add functions for card on_hover and off_hover signals and connect 'em.
...
  1. I often find myself reading through functions twice, first to realize what it does (if the function name doesn’t give it away), and then how it does it. Comments help out with the first read-through.

So my generic recommendation is that comments should be used for remembering, not understanding. (This is from a perspective that has never worked on a group code project before.)

If you are working with other people on the same code base , then yes.

If you are a solo dev then yes when you have some code that may not necessarily seem obvious at first glance, and you may end going back to months or even years later.

Otherwise, no I dont think its required.