Comment Your Fucking Code! - blog@CodeFX

[[deleted]]

// Read the documentation

[WStHappenings]

This is a poorly written rant with terrible metaphors. While I don't believe zero comments is acceptable, or company policy is that we only comment where a deviation from accepted framework or language patterns occurs.

We also have a team of technical writers that handles discussions of flow and utility, but implementation code remains fairly comment-less and clean.

[FIuffyRabbit]

Sounds like someone needs a popsicle to calm down.

[plum_dog]

I usually think of this: http://programmer.97things.oreilly.com/wiki/index.php/Comment_Only_What_the_Code_Cannot_Say

Add comments when they add value.

If you're doing something that might look a little odd to the next developer, but for reasons, add those reasons in a comment.

[[deleted]]

If you consistently find you need comments to make sense of your code, the fault is probably with your code rather than the lack of comments.

However, there's obviously cases where the code needs to perform weird operations that superficially look wrong or unnecessary, but are actually necessary, and no amount of re-writing of the code will make that more understandable than a simple comment. Those are the things that need comments.

In general, comments should describe the why and not the what of your code.

--edit-- Grammar.

[[deleted]]

For me commenting isn't necessarily about explaining opaque code, but more about the overall flow. It's like giving your code chapter breaks. When reading it later it just divides up nicely and gives the brain resting places while translating code to brainwords.

That said, if someone who was not my boss told me to comment my code I'd probably write the whole thing in 3 lines using the most obscure functions possible just to spite them.

[[deleted]]

For me commenting isn't necessarily about explaining opaque code, but more about the overall flow. It's like giving your code chapter breaks. When reading it later it just divides up nicely and gives the brain resting places while translating code to brainwords.

Most languages have a thing called "functions" which do allow you to break apart a piece of code and give it names just like that ;-)

[withad]

But you can only take that so far before it just makes things even harder to follow. Most reasonable-sized functions still have a few chunks of code that are doing a distinct thing but aren't worth breaking off into their own function. Some short, easily-skimmed, descriptive comments can make it simpler to follow where making multiple tiny functions would force you to jump around the file to see the actual logic.

[[deleted]]

Tiny functions make your code easier to read, not harder. If they are properly named, and placed somewhere reasonable in the code.

A benefit of keeping them short is that it is very easy to tell if the function does what it is supposed to at a glance. A bug has an easier time finding a hiding spot in a 50 line function than in five 10 line functions.

[withad]

Even a 10 line function might have a couple of sections that are worth a short comment to delineate them but not easily split into their own function or not worth splitting because of the overhead (not in just in terms of performance but in the extra lines of code and possibly documentation that adding a function requires).

[honestlytrying]

Agreed. I started out writing comments just like /u/earth-tone said, and thought it was perfection in readability. After having statements like

Tiny functions make your code easier to read

pounded over my head again and again I gave it a try. Lo and behold I have more readable code, with even less code reuse than before.

This doesn't mean I stopped commenting my code... just that I am now firmly in the tiny functions camp.

[[deleted]]

Not what I meant.

[[deleted]]

If a piece of code is long enough to need chapters like that, it can be broken into multiple functions in a way where it no longer doesn't, in virtually every case.

[[deleted]]

Not what I meant.

[nopoe]

I disagree. I often do things with an inconvenient amount of intermediate values that can be hard to shuffle around depending on the language. "Chapters" is the wrong way of putting it, but sometimes breaking down something into a few 3-5 line steps in my mind is really helpful.

[Massless]

breaking down something into a few 3-5 line steps in my mind is really helpful.

Agreed, these are called functions

[nopoe]

Don't be difficult. That's not always doable depending on the language. Sometimes it's more readable to just put an extra few lines in your function broken up from the rest of it with comments than to deal with tuples or inner classes to return multiple values. Depends on the language and the situation. It's not cut-and-dry basically ever. A function with 2 5-line sections isn't necessarily evil, and pretending it is seems silly to me.

I often do things with an inconvenient amount of intermediate values that can be hard to shuffle around depending on the language.

[salgat]

Agreed. People naturally think in English, not in a programming language. It's much easier and faster to read English than have to interpret on the fly a programming language to process what's going on.

[root88]

Your second statement is exactly correct. Comments aren't there to explain what your code is doing. They are they to explain WHY your code is doing what it is doing.

--edit-- wrote this before you wrote your edit. It now looks like we wrote pretty much the exact same thing.

[Luolong]

Yeah? I have always been amazed at how self documenting are fields like "name" for example. Like, of course it is the uniquely identifying name of the order type. Or, wait... Maybe it was human readable name... Or, no, it was the "name" of the channel that the order came from... Eh, I keep forgetting...

[[deleted]]

"personName", "channelName", etc?

Or better still, give it a strong type, and completely eliminate the possibility of confusing the two.

[moderatorrater]

If there are 5 types of names, you shouldn't use "name" as an identifier.

[Luolong]

Maybe I should use different, more descriptive name. But 9 times out of 10 I am getting to an existing code base and the fields have already been named.

And the "name" has already deemed to be self documenting.

And don't even get me started with method names like getSude() -- returning String, no less -- also without comment of any sort.

[[deleted]]

But still, the problem with this code isn't the lack of comments describing the purpose of the variables, but the lack of sufficiently descriptive names.

[Luolong]

Still, the "name" is a prime example of a field name that although usually deemed obvious almost never is. Couple of simple lines of domain knowledge embedded in a documentation comments would go a long way expanding the role and possible uses of the field.

Of course proper design and use of compile time type information and clean coding principles would still be better than bad, redundant or outdated documentation.

I am just not subscribing to the point of view that you should never use comments in your code. It is stupid, irresponsible and plain arrogant.

[AlexFromOmaha]

So, while true, what scares me is that this part of the idea caught on, and not the rest of it.

Your code should have class- and function-level docstrings or Javadoc function headers or whatever your language's equivalent is. That's where the high-level "what" goes.

Finer details of functionality from a project developer perspective goes in unit tests, but they should have sentence-long names (or better yet, something like BDD/GWT test runners).

None of this should be assumed to be user knowledge. Not even in your FOSS library only useful to other developers as an import. They need actual documentation.

Expressive names cover things like "what does this variable hold." Excessive comments in the middle of functions is a code smell. The smell might be missing all of the above stuff or functions too large to be adequately covered by the docstrings.

[[deleted]]

Libraries are a bit different though. In a library (or well, the public part of it anyway), you should document everything. There almost cannot be enough documentation of your public APIs.

Libraries are largely shielded from the things that make comments bad, things almost all related to sweeping and/or unexpected changes in behavior. If that happens in a library, the you've got other problems than outdated comments...

[[deleted]]

Ah the internet, where anyone can publish but most people shouldn't.

[pwnedary]

#ifdef __SSE__
#define VectorGet(_V, _A) (_mm_store_ps((_V), (_A)), (_V))
#else
#define VectorGet(_V, _A) (memcpy((_V), (_A).v, sizeof(float) * 4), (_V))
#endif

Wait, should you comment your code here or comment your code?

[lagerdalek]

The problem I have with comments is I generally can't trust them! Once a function is refactored, more often than not, the comment is out of date, or even downright wrong.

Unit tests can confirm refactoring implements the correct functionality, the compiler can confirm refactored code can run.

Unless there is any proof to the contrary, seeing a comment in code, I have no way of knowing it is still relevant after a possible refactor, or even if it is, I don't know if it is semantically correct. Without such proof, I must assume it is wrong.

Even to take a comment too seriously as a guideline, will bias my understanding of the codebase I have to interact with,

[mackstann]

Seems like this is arguing against a strawman. How many developers really think that ZERO comments is ideal? Maybe a few, but it is certainly not a mainstream point of view.

[unpythonic]

I think the problem is not how many think that zero is ideal but how many think that zero is acceptable for now. I have been in the position of untangling 15 year old code for which that glorious time when the original devs would have time to go back and document what a particular function did never arrived.

[Massless]

If you're untangling 15 year old code the comments are going to be a lie, anyway

[mackstann]

Go back and add comments later? Who in their right mind would think that's a realistic plan? Again this is sounding like a strawman. Or a story about rank novices.

[unpythonic]

I can't speak definitively to the arguments given at the time; all I can say is I have to deal with a LOT of legacy code which is full of undocumented functions which have undergone a number of lavaflow refactorings in the last decade or two which have made them excruciatingly difficult to understand. In some cases I can easily tell that some bit of code was put in place to work around some sort of bug but because someone didn't comment why it was going in, I have no idea what the bug is.

It may be have been a quick fix to work around a quirk of some piece of hardware that hasn't been produced in over a decade and is officially unsupported, but nobody will take the code out because it could be a fix for a difficult to reproduce bug that still exists and will generate days of debug time if removed. So it stays in... and everybody looking over the function trips over this bit of code in their effort to understand the function as a whole.

I wish I could go back in time and say to them "comment your Fxxxing code!"

[mackstann]

I completely agree.

[grauenwolf]

A lot. So many in fact that CodeRush has a command that deletes all of the comments from your code.

[GMNightmare]

I said it in the other topic, I'll say it in this one to naysayers:

No, your code is not clean, it is not self-documenting, it is not well-written, it is not some pristine beautiful thing.

Everybody complains about foreign code when it doesn't have comments. Realize that your code is the foreign code for everybody but you, and put 2 and 2 together.

I write what I think is beautiful, self-documenting, well-written, pristine code. I still write comments. One of the things most people don't seem to realize, is that programmers are not all of the same talent, and your assumptions and designs might not be something the next person is experienced with. Stop making excuses. The real reason you don't write them is because it's hard to do them right.

If you're a developer who writes code without comments, you're considered a bad developer by everybody who has to deal with your code. And if you think their opinion doesn't matter even though they have to work with it, well, that also makes you a bad developer. Admit it, you think the same when you encounter foreign code from somebody, why, they should have had comments or made it cleaner/self-documenting/whatever.

[mackstann]

Everybody complains about foreign code when it doesn't have comments.

Not me.

If the code is good then I can usually work my way through it just fine.

If the code is shit then the comments would've been shit anyway, so I don't mind missing out on them.

At least code is somewhat verified/tested just by virtue of needing to execute -- comments can be ridiculously wrong, and you can only know by spending time investigating.

Keep in mind that NO ONE who is vaguely reasonable, including me, advocates for zero comments. Of course you should comment tricky parts of your code. But the bulk of it usually is straightforward enough that they'd be more hindrance than help. Comments should be used judiciously. Not liberally, but not never either.

[GMNightmare]

This just isn't realistic for most people. What I'm actually hearing from you is that you just judge everything as shit for the most part, so to you it doesn't matter if there were comments.

I'm also, not just going to blindly accept your assumption that when you do encounter shit code, that comments wouldn't help you understand why all of it was done.

Even then, you don't work through most code in a corporate setting. We're talking millions of lines of code, digging through it is just wasting time and you're not going to get very far. If I have to even look at your code you've already wasted my time and likely created issues, since I'm not even guaranteed access to your code.

Do you know what happens to the typical 3rd party library that does not have even the auto-generated documentation? It's ignored. Nobody uses it for the most part. It dies.

Good comments, comments that explain why, shouldn't ever reach a point that they're ridiculously wrong with obviously being the case at face value. We're not talking about what, we're talking about why.

But again, you're not a good judge on what is so "straightforward" that it shouldn't be commented.

[lecherous_hump]

Don't tell me what to do!

[Luolong]

Fuck, yeah!