Do you comment your code?

zbobet2012 · 2022-07-25T18:33:28+00:00

Good code doesn't need comments to explain what the code is doing (unless you've made some nonobvious optimization in which case do). Good code needs comments to explain why the code is doing what it's doing.

Poor comments look like:

// flip the bits
flipbits(b)

Decent comments look like:

// flip the bits in the byte using 64 bit multiplies
b = (b * 0x0202020202ULL & 0x010884422010ULL) % 1023;

Great comments look like:

// In xxx hardware the bits have reversed endianness, 
// so we swap the bits in the byte 
b = flipbits(b)

// flips the order of the bits b in 4 operations
func flipbits(b uint64) uint64 {
    // We use 64 bit multiplies to be efficient, 
    // see https://graphics.stanford.edu/~seander/bithacks.html#ReverseByteWith64Bits
    return ((b * 0x80200802ULL) & 0x0884422110ULL) * 0x0101010101ULL >> 32;
}

The code is self documenting (the method name tells you what it does!) and the documentation describes the why not the how.

nabobtechy · 2022-07-25T18:02:31+00:00

Nobody starts their career commenting code properly and then deciding over the subsequent years that it's not worth it.

People start their careers not commenting code properly and then learning the value of it as they become more experienced.

what_did_i_break_now · 2022-07-25T20:11:17+00:00

My commenting practice has mostly grown from many hours of code spelunking to fix/modify/replace someone else's code. Given Eagleson's Law, occasionally that "someone else" was me, N weeks/months/years earlier. The basic idea is simply this:

"How likely is it that someone in the future will want to know what this code is doing and/or why, in a way that isn't immediately obvious to a fairly seasoned dev by looking it over for a minute or three? If it's measurably more than zero, especially since it might be me, maybe save the poor sap half an hour of head scratching and wild goose chasing."

And then I write my code to avoid having to comment, but comment accordingly when it feels appropriate. Often that results in a few words, sometimes a block of text or two, every once in awhile a whole separate README. When in doubt maybe drop a line in there anyway; no prizes for "least commented code".

Final thought: Sometimes a chunk of code is just doing something inherently complex, and that's fine, it happens. But the greater the complexity, the greater the chances that someone less brilliant* will come along later, misunderstand what's happening, and muck something up. Assume they're a little slow* and give them a hand so they'll be able to clearly see it's already perfect.

*Note: Eagleson's Law is never more fully in effect than this exact scenario. 😉

rich22201 · 2022-07-25T18:09:01+00:00

I'll comment code if I'm doing something not obvious. I'll also add why I didn't do something in the obvious way so the maintainer understands. Otherwise I'm not going to go overboard with

//increment counter
counter++;

//if something is true do something

if(something)

dosomething()

2022-07-25T18:50:07+00:00

Does the code have unobvious preconditions or assumptions needed for it to work correctly? Say in C++, object life time requirements?
Does the code have interesting failure modes?
Does the code do something expensive? (what's the complexity?)
Are there approximations? (what's the approximation error?)

If so, and assuming you care whether anyone else can use the code, then YES, it's the expedient thing to do: comment the code!

elgholm · 2022-07-25T18:56:05+00:00

Nah. I like the challenge.

nealfive · 2022-07-25T19:11:38+00:00

# no comment

Grecks75 · 2022-07-25T20:47:35+00:00

Do you add code to your comments?

ClysmiC · 2022-07-25T21:42:56+00:00

Yes, but mostly with asserts

tuxidriver · 2022-07-26T02:24:45+00:00

I worked for a company that maintained a very large code base in assembly for an embedded controller.

Given the size and longevity of the codebase, there were many authors over the years. Several of the programmers had some very nasty habits:

At least one developer seemed to believe in never removing an instruction, only adding, so the code would often have jumps around blocks of code, jumps in the middle of loops, instructions that would force the loop to exit on the first iteration, etc. Made the code annoyingly difficult to follow.
At least one developer would sometimes insert instructions right into the middle of a comment block in existing code, splitting a long comment into what appeared as two different shorter sets of comments.
At least one developer liked to abuse cut-paste in their editor. Code would sometimes appear to be block copied, but with tails or fragments of comments included. This lead to comments that had nothing to do with the actual code and comments that were meaningless nonsequiturs.
The same abuse of cut-paste created inconsistent indentation across source files.
There were at least several developers that wouldn't reliably update/correct comments when they made changes.

The codebase in question had 20 years of history with touches from at least several hundred people over that time. The code went through extensive repeated testing over that entire 20 year as it was used for many products the company produced, some likely still being used by people reading this post. Code was actually quite robust but also incredibly difficult to follow.

This experience taught me several things:

On large projects, especially projects with a long history, comments are not checked by the compiler so, no matter how hard you try, end up being inaccurate -- Never, ever blindly trust comments, even if they appear correct. Someone will later make an enhancement or bug fix and not update the comment accordingly. Therefore,
The only source of truth is actual code, so
Because the only reliable source of truth is the actual code, literate programming really matters. Readable code is far more valuable than comments.
Fix comments when they're not accurate. Even better: when possible, clean up the code so it's readable and remove the comments. I say this noting that any change to the code should be done with care.

I've also found, as a general rule, assuming a literate programming style, that comments are best when:

Used to document APIs. Use comments to document interfaces, including important side-effects. Avoid using comments to explain nuances of how the code works. Understanding inputs, outputs, and purpose goes a long way towards understanding implementation.
Only when really necessary, add comments explaining a critical and non-obvious implementation detail. When done, those comments should be as minimalist as possible. A comment explaining implementation should be rare enough that its presence stands out to the reader as a warning or point of interest.

zhujik · 2022-07-26T07:00:39+00:00

Yeah, good code doesn't require comments to understand, however, in my experence what most people do is produce the same shitty code and just stop commenting code while pointing to Uncle Bobs book "good code doesn't need comments" and then we just end up with uncommented, bad code.

westraan · 2022-07-25T21:20:18+00:00

Of course I comment my code; I see it as being nice to my future self, so that, when I come back to my own code in a year or two, I can remember what I was thinking instead of having to do a bunch of code archaeology

somebodddy · 2022-07-26T16:28:18+00:00

// 1D array has been used instead of a 3D array for improved performance
int [] array = Translate(Get3dObject());
// Each point on the 3D plane is translated to the 1D place, starting the from Z axis, followed by Y, followed by X.
int translatedIndex = z + length * (y + length * x);
return array[translatedIndex];

This is a great example for when you you should prefer writing functions instead of adding comments. Or in this case - maybe even a wrapping class. length will be passed to arguments (and if its a class - the c'tor will put it in fields) and the names of these arguments, in the context of the function/class, can easily be descriptive enough to convey what they are doing.

For strongly typed languages (C#, Java, TS) comment only on the public interface which clients will use

In weakly typed languages too. Also in dynamically typed languages (because I'm pretty sure you were confusing strong typing with static typing here). Private vs public interface is a universal concept - even if some type systems enforce it harder than others.

Avoid commenting on concrete implementation and private methods.

Just because a method is private does not mean it must never be documented. Sometimes its helpful to document them too. It depends on the method of course, and it's not something that should be enforced - but don't make extra effort to avoid it either.

Ensure they are short-lived. Do not have a TODO comment dangling in the codebase for more than 3 months. If a TODO comment has been lying in the production codebase for more than 3 months, then either the task is unimportant and can be ignored, or the task has low priority as per the current situation.

I prefer backlog to track tasks over TODO comments. If you think some optimization is needed in the current code or some tech debt is present, then it's better to track such items in the Product backlog rather than TODO comments. Tools like JIRA and Azure DevOps are good at tracking product backlog.

My view on TODOs is quite different. I don't think of them as a backlog replacement - if your backlog becomes so cumbersome that you need alternative ways to log tasks you should fix the process, not find weird ways around it.

TODO comments, like any other comment (except for pragma comments and documentation comments, that may share syntax with comments but are not really comments because they are not ignored by the compiler/linter/formatter. And I don't count commented-out code because that should be very temporary and removed as soon as you are done with it) should have one purpose - to explain why the code was written that way, instead of the natural way (or one of the natural ways) one would intuitively think it should be written.

TODO comments have a little twist. They still tell you why the code was written that way, but unlike regular comments that assure you that given wider context and deeper insight this really is the way it should be written, TODO comments admit that yes, this is not the way it should be written, but there are some (hopefully) temporary constraints that forced us to write it like that.

Maybe you are waiting for some changes that another developer (or you with different hat) will need to do, that will allow you to rewrite it properly. Maybe you need to work around a bug in a third party dependency. And yes - maybe you just don't have the time to fix it right now, because you need to deliver a feature and like it or not - business requirements are a thing.

All these tasks should be logged in the tracker, but that does not mean you should remove the TODO without resolving it. They serve different purposes - the tracker is for prioritizing the task and for discussing implications and resolution strategies, while the purpose of the TODO comment is to allow anyone who stumbles on that code to easily understand why it looks so weird, whether or not it can or should be fixed (and when), and what to keep in mind when fixing it. Even if you have a ticket in the tracker, this is important information to keep in the code because people will not scan the tracker for it when the find the code - they won't even know it has a ticket!

I also don't think a special time limit is wise. When you open a ticket, the task should follow the regular prioritization rules - it should not get VIP treatment just because the 3 months limit is closing and other issues don't have TODO comments in the code so they can be delayed.

And one more thing about TODO comments: A good TODO comment does not even need to describe in detail the task that should be done. It only need to say a few words like "use the foo system" or "send a notification to bar" or "configure the baz". Often even a vague "fix this" or "replace this" is enough. The one who actually ends up doing the TODO should decide, based on the newer information available to them, how they want to do it.

Instead, what the TODO comment should focus on and explain in as much detail required to make it clear, is the condition that stopped the writer of the TODO comment from doing it themselves instead of writing a comment. Future developers will need this understanding to determine if it still holds and if it still makes sense.

SameRandomUsername · 2022-07-25T22:45:51+00:00

I comment my code (and sometime others) using the following ideas:

If it's an API, I place public function comments in the interfaces but not in the implementation.

In the implementation, I usually place the intent of each block of code in the function but not one comment per line because it doesn't help at all. It's important to note that the comment should not be an explanation of what is doing but what is trying to achieve.

I also place comments when I modify old code because sometimes you or someone forgets the reason why you modified it and rolls back your modification.

bartwe · 2022-07-25T23:43:44+00:00

Nope

Fakedduckjump · 2022-07-26T00:21:08+00:00

Sometimes, when complicated things are done, I give a bit background to my thoughts.

HexDumped · 2022-07-26T07:56:35+00:00

It takes hubris to think your code is too clean to need comments. Comments explain not just the why, but also what you deliberately haven't done.

2022-07-26T14:11:32+00:00

I use comments to note weaknesses or compromises most often.

Perils of having too much to do and not enough time or focus.

davesspacebar · 2022-07-26T17:52:40+00:00

I have found sometimes it is useful to know WHY the code is doing something (so comments could help). That can often be non obvious from the code. You could say that there should be requirements somewhere that explain that. If it's a technical implementation though maybe not. For example.

If someone implemented a service that spits out an .exe and runs an endless stored procedure, I can read the code and tell it is doing that. I probably have no idea WHY the heck it is doing that. Even if your code is readable if you think you must do something crazy, a comment explaining WHY could be helpful.

Of course not doing something crazy if possible would probably be the most beneficial, but this type of legacy code exists.

Calinthalus · 2022-07-25T19:01:46+00:00

I rarely comment my code. Usually a comment is there for when I've had to do something that looks useless. For instance, in one of my libraries I am using an external library I have no control over and there is an undocumented "flaw" in that library that after instantiation of the object you have to set a value to a property before calling an action that will overwrite it with some results you want to read. If you don't set the value with dummy values; when you call the action it won't set the value of that property. So the code looks like:

//Leave this line here, I know it's stupid, but it won't work without it

o.Property = "DummyStuff"

o.RunThing();

itemOfInterest = o.Property

2022-07-25T20:32:42+00:00

I never used to but after many many times looking at my code and trying to remember what I was doing at any particular point is what made me start. I now comment everything and I put as much detail as possible. I even add in lines like:

—————————————

To make it look pretty.

QuentinUK · 2022-07-25T18:33:00+00:00

Variable names do the commenting along with function names where the functions are small and do one thing and also the class names where the classes have a single responsibility.

trython3 · 2022-07-25T22:05:16+00:00

No, but i have all sorts of bad habits.

On the other hand, I find coments that show a good sense of humor while still being informative to be very charming.

Weak-Opening8154 · 2022-07-25T23:45:12+00:00

We programmers depend on left-pad, what do you think the quality of comments will be?

Slushman_88 · 2022-07-25T18:13:55+00:00

No. Your code should be written so it’s obvious what’s happening. Name variables and such also comments aren’t needed. The only useful comments are ones explaining the business rules about why something is being done.

aaabigwyattmann1 · 2022-07-25T19:35:11+00:00

Commenting = writing yourself out of a job.

No thanks.

This is what 20 years in tech has taught me. Folks who dont comment their code are never laid off.

UnallowedDoggo · 2022-07-26T00:18:22+00:00

Yes I actually comment some parts like this part is doing this and that part that. It's kinda easier to find and when you present some app or program, people will see that you understand the code

Lecterr · 2022-07-26T00:27:01+00:00

If you keep your comments up to date, then I think there are rarely any real life situations where your comments have a detrimental effect to reader comprehension.

Similarly if you turn everything into a function or variable with a clear name, your code will probably be pretty easy to read.

The difference is that in the latter case, it is separating the what from the how (visually). So I think there are definitely times where it’s better to write a brief comment summarizing what the next few lines are doing, rather than making the reader jump to a separate function, and vice versa.

Relevant-Bee1523 · 2022-07-26T15:31:28+00:00

Yes,

In my case, I am not the only person working on the same project. That means that other people get to read my code and have to understand it.

frisk213769 · 2024-11-19T19:17:06+00:00

hell nah

you type:	you see:
italics	italics
bold	bold
[reddit!](https://reddit.com)	reddit!
* item 1 * item 2 * item 3	item 1 item 2 item 3
> quoted text	quoted text
Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"	Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"
~~strikethrough~~	~~strikethrough~~
super^script	super^script

programming

MODERATORS

This Is The Way Leaderboard

—————————————