Jump to content
  • Advertisement
Sign in to follow this  
EbonySeraphim

Commenting in tight loops

This topic is 2816 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

I hope this is a topic that isn't better suited for the GDLounge, but I was writing code in a tight loop and was considering the need to comment what's going on, but then realized that it really is hard to explain what is going on with code that deeply nested. Does anyone else feel that way with code in tightly nested loops? You'd have to write a heavy paragraph or two just to explain how that work in that loop fits in the bigger picture, and even worse if you have to explain how and why every variable used in that loop is used.

Share this post


Link to post
Share on other sites
Advertisement
If it's too deeply nested, consider refactoring the loop, or the contents of the loop, into it's own function.

Most of the time, my own loops are understandable enough that I just comment what the loop itself is doing, and not the contents of the loop.

Example comment:
//Iterator over the array, checking for 'dead' elements and removing them.

However, that's most of the time. Occasionally, I write a function that's in bad need of refactoring, and I don't know how to refactor it, and my comments are hard to word properly. That's when I realize that I probably coded it wrong, and I should rethink what it needs to do, why it's doing it, and how it could be recoded better. Keyword there, 'should'.

Share this post


Link to post
Share on other sites
I don't really see how comments in a tight loop are much different from comments anywhere else. Ideally the code is self-documenting so that it's obvious enough to anyone else what you're doing and why. If that's not possible, you write a quick comment or two. If you find the need to write in-depth documentation, then it's either better suited to a proper documentation medium (eg. Wiki) or it means that the code could be simplified anyway.

Share this post


Link to post
Share on other sites
Mostly you pull the nest out into separate functions(They are small functions only called in one place so they are almost guaranteed to be inlined). If you can't explain it one level at a time then perhaps it is bad code.

Share this post


Link to post
Share on other sites
Writing two paragraphs about what it does is not necessarily a bad thing. Most code is (or should be) self-documenting, at least if the header has a description of what the module does and is used for. One line comment here or there, but mostly obvious what's going on.

But sometimes you need to do something fancy and complex, and that's when you say "screw self documenting" and write what works, along with a detailed explanation of what you're about to do, what assumptions you're making, any traps that someone might fall into editing it later, and so on. Don't overdo it, don't underdo it. Sometimes the comments are all up-front, sometimes paragraphs dispersed through the code, generally depending on how long the tricky section is.

I generally write comments mainly to
1. assist debugging
2. reduce chance of breaking things when modifying later
And mainly with other coders in mind, as I can usually remember what I was thinking pretty easily even a long time later. So you want to keep it short enough that they will actually bother reading it, but detailed enough to help them.

It's a fine art.

But of course, you might just need to refactor your code.

Share this post


Link to post
Share on other sites
Sign in to follow this  

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

We are the game development community.

Whether you are an indie, hobbyist, AAA developer, or just trying to learn, GameDev.net is the place for you to learn, share, and connect with the games industry. Learn more About Us or sign up!

Sign me up!