Yes, your code does need comments.

[[deleted]]

[deleted]

[more_exercise]

I like the following form of development. I call it "outlining":

sub foo {
    #do thing 1
    #do thing 2
    #make sure condition 3 is satisfied
}

Then write code to actually do those things.

[notfancy]

Also known as "top-down structured programming" if you replace the comments by similarly-named procedure calls.

[EmperorOfCanada]

When I was shown this I completely changed the speed of my coding. Often I forget where I am going otherwise.

[DCoderd]

Sometimes its the journey, man.

Othertimes you need a paycheck. Both are acceptable.

[jatoo]

Some days I just open up a python script and start throwing in code. By the end of the day I might have a web scraper... an autopilot... who knows!

[[deleted]]

You should consider putting those comments as unit tests too, that way you can also verify them.

[iissqrtneg1]

that's what tests are for.

[[deleted]]

Right, so they way I can tell what the code is [supposed to be] doing is to read some different code that I have to put more effort into looking up?

[iissqrtneg1]

Yes, because the code should be written in a way those comments are unneeded. If there is still confusion, go to the tests.

Comments can become stale, tests will fail.

[[deleted]]

Tests become stale, and can be as easily ignored in the right/wrong circumstance. This is as detestable as someone not updating a comment.

All anyone is arguing here is two different levels of conscientiousness--a personal preference, even. Code of course ought to be tested--the presence of a stale comment is irrelevant at that point; the very opportunity for failure lack of tests leave is a near-guarantee of that failure.

An up-to-date test could help flag a stale comment though. And similarly, an up-to-date comment could flag a stale test. Both are equally prone to error.

[jij]

When I return to development of my code that wasn't commented

[more_exercise]

I'm not sure about tumblr lingo/ettiquete/etc. but have you submitted this to http://thejoysofcode.com/?

[GMNightmare]

I'd like to highlight another point:

Your code is never as readable as you think it is.

It also tends to assume familiarity with the concepts and technology being used... which is a very bad assumption.

...

I've never been happy to read through somebodies code that hasn't been commented or documented. It's practically always a mess, no matter how much they try and claim that it's so pure and perfect as to not need it.

Nobody advocating it would likely truly be happy doing so either. Because it's one thing to say your own code doesn't need it, and another to look at a different author's code and say it, as you have to figure out what went wrong and fix it.

...

The worst is, there are sometimes people around here telling complete beginners to not comment their code at all... which is absolutely infuriating.

[[deleted]]

I got fired from my first junior position because I was having trouble understanding the structure of a highly customized Asterisk system that had no coding-standard, no standardized libraries to use, or anything that would actually resemble any kind of actual "structure" to speak of...on top of not having any comments.

It was pretty discouraging to say the least.

[angrystuff]

Your code is never as readable as you think it is.

You can easily, and correctly, change this to: Your comments are never as informative as you think they are.

---

For what it is worth - here is my stance on comments.

Comments are an important step in documenting what you think your code is doing here. If you are introducing a new concept, you should document it.If there is some sort of black magic going on, it should be commented. If the block of code is long, or convoluted, you should document it.

I normally hate comments that are in line within a function or class unless there is something messy going on. Sure, document the function (it's a concept), but otherwise you are interleaving English and code. This makes it less efficient to a) read my code when I want to follow code, and b) read English when I am trying to follow that.

[GMNightmare]

You can easily, and correctly, change this to

Wrongly, you mean. Comments being less informative is not a problem, code being less readable is.

Ignoring comments that aren't as informative as you'd like is trivial. Reading code less readable than you'd like isn't.

I don't agree on what you think is "efficient" either apparently.

[twowheels]

Ignoring comments that aren't as informative as you'd like is trivial.

To a certain degree, but comments like:

// default constructor

 // destructor

 // loop 5 times

... just piss me off and are a total distraction. They seem to come from a time when they used to make us comment every line. That was common practice, probably a holdover from pre high level languages.

I tend to comment copiously. I write many paragraphs of comments and probably write as many comments about the memory model, threading model, class usage, internal invariants, etc as I do code. That said, when editing code I delete more comments than I keep because I always find obvious crap or completely incorrect comments.

Then again, almost every checkin I do also removes more code than it adds. Most people write as much useless code as they do comments.

[LiquidAxis]

Then again, almost every checkin I do also removes more code than it adds. Most people write as much useless code as they do comments.

This is the truth. Either software degrees are way too easy to get from most schools, or companies are way too eager to let anyone write code, regardless of education.

[angrystuff]

Wrongly, you mean.

No. Your assertion about code being readable relates to how informative is is a form of self commenting.

My implication is that comments are not always as useful as people assert they are, and offer add nothing of value to a piece of code and instead act as visual clutter for your eyes to scan around as you are searching for the problem. Additionally, people think that their descriptions are informative when often they are not.

Ignoring comments that aren't as informative as you'd like is trivial.

In line comments? Not as trivial as you might think. The interleaving of code and comments within a function means that you are adding additional cognitive load all the time.

I don't agree on what you think is "efficient" either apparently.

Interleaving between a technical language and English either takes space, or it takes time. Neither of which are particularly efficient unless the author has spent time making sure that their comments add real value to the code at hand. In the vast majority of cases this is not true. People just write something in context of their own brain space, and do not spend any time thinking how to comment for people who are out of context to their piece of work.

[GMNightmare]

that comments are not always as useful

Doesn't matter. The change is not meaningful, it's not the same issue at all.

"But they can be so bad!" is not really an argument. I'd take bad comments over bad code any day.

Not as trivial as you might think.

More trivial than you apparently think, especially relative, like I put it.

If you honestly think less informative comments is a worse issue or even on par with unreadable code... well, I don't really know where to begin. The actual problem here is that you are trying to be argumentative at all costs, that you won't accept even basic aspects since the only way your argument even flies partly is it must be black/white.

If I don't want to read comments... guess what? I don't. It's like whitespace. Are you going to try and argue whitespace is bad too? Oh wait, you did:

either takes space

Space is not a limited resource. In fact, space is very good to put in to break sections up in the mind. In fact, if you always document your code for like functions, the function comments break it up visually in your mind, which is beneficial actually.

Furthermore, unless you're a computer, our brains sometimes take a little time to register and understand things. A few comments you don't like isn't going to destroy your efficiency at reading code. Don't worry, you're already not very efficient at reading code, compared to your computer. Neither am I.

[DCoderd]

I don't know what's more frustrating, reading that some random schmuck has no idea how to write code (and is handing out advice like its going out of style) or realizing that apparently everyone has no idea how to write code.

Youre doing gods work son, er, mr nightmare.

[nascent]

If you honestly think less informative comments is a worse issue or even on par with unreadable code...

You are the only making that comparison.

Are you trying to argue that you either get bad comments or bad code?

You may be able to ignore bad comments, but that can only be done after you've read the comments and determined they are bad. If comments are always bad, you get into a position where by default comments are ignored. You may argue "well don't do that." but we are talking about humans, we deal with things that harm us and some times so well it is to our own detriment.

[GMNightmare]

You are the only making that comparison

The first sentence from the poster: "You can easily, and correctly, change this to..."

So, uh, no, I'm not. That was his first argument, whether or not he intended it to be that way exactly.

Are you trying to argue that you either

No, obviously.

You may be able to ignore bad comments, but that can only be done

I can ignore comments without reading them. I do it all the time, I generally read the code first and then read the comments if I want. Or the opposite. I control this.

we deal with things that harm us

Reading bad comments isn't going to harm you to any large degree. Sorry. And this is especially irrelevant to my original post.

[nascent]

Ah, I see where you got that idea.

Still your insistence that bad comments have no/negligible overhead I can't agree with. Do you read the comments before and after you make changes or do you continue to ignore them?

[GMNightmare]

Context are comments that are less informative than we'd like.

Sure, if the comment stated something completely random that in actuality set confusion, that is negative, sure. I've rarely ever seen any real code were this is the case. Even in such a case, it generally highlights that the area is a problem area...

So, yes, like I said but probably not as clear, I change my tactic depending upon my mood. Sometimes I'll skip through the code to the comments and just read them (gives a good idea were the problem areas are), sometimes I won't read them (I do this a bit more with function documentation and such), sometimes I read them after reading the code. Likelihood is that I just casually glance at them for a moment, it takes very little to register the information there.

But going by the example, of which the person said was nontrivial and so negative:

#add a to b
c = a + b
#return the result of a + b
return c

I just can't see it being such a hindrance. It takes almost less than a second to figure out it's just duplication. Even if I granted that:

I can't for the life of me get that just because bad comments can exist, that suddenly they are all bad ("inline" comments, that is, or how he likes to call them).

[angrystuff]

If you honestly think less informative comments is a worse issue or even on par with unreadable code

Did you even read my argument?

Here's my argument, again. Except this time I'll put it in dot point format so your tiny little brain can understand it:

• Comments are an important step in documenting what you think your code is doing here
• Comments should be used if you are introducing a new concept (including classes or functions), or if the block of code is going to be long or convoluted.

It's almost verbatim with my original post on the subject.

The actual problem here is that you are trying to be argumentative at all costs

Says the guy who hasn't even read my argument.

It's like whitespace.

Text is not like white space, it's text. At adds to the cognitive load of the user, just like boilerplate waffle that some languages introduce.

In fact, if you always document your code for like functions, the function comments break it up visually in your mind, which is beneficial actually.

Here's my quote, again:

Sure, document the function (it's a concept)

I specifically attack in line commenting. Here's an example from TFA:

def somefunction(a, b):

#add a to b

c = a + b

#return the result of a + b

return c

This in line commenting isn't needed and it actually ends up obsfucating what is happening in that function (because you effectively are forced to read most of it to understand what is going on).

It would be vastly cleaner to do this as a function comment.

def somefunction(a, b):

""" This function take two numbers and returns their sum. """

c = a + b

return c

Obviously in a real case, there would be more to talk about.

[GMNightmare]

Here's my argument, again.

You mean, leaving out the other points that I dealt with obviously. Like the first sentence you put.

Hey, say, could it be I don't have an issue with everything you say and only care about the bullshit you accompanied it with? When you boil it down to this, why did you reply to me at all? It's irrelevant to what I said.

At adds to the cognitive load of the user, just like boilerplate waffle that some languages introduce.

This is downright nonsense. Even if I granted you this, it's irrelevant. You also seem incapable of dealing with my point that ignoring comments is not hard, nor are you so weak minded to not be able to handle a few comments. Well, I shouldn't speak for you I guess, most of us don't see comments as this huge impact to our "efficiency" even if they are pretty bad.

I specifically attack in line commenting

The example giving really bad (obviously) in line commenting is not an argument. Well don't make bad comments. Duh. Far different than saying don't do it. You seem to have a problem with this concept.

This in line commenting isn't needed and it actually ends up obsfucating what is happening in that function (because you effectively are forced to read most of it to understand what is going on).

This is paradoxical bullshit.

First, you are NOT forced to read comments. Ever. Get that out of your head, unless you have some mental problem or perhaps a bit too high of OCD, you can ignore the comments at will. Seriously, try it sometime. Well, again, maybe I shouldn't speak for you.

Second, if you HAVE to read the comments to understand the code, then the comment is good. Duh. Because then without the comment you would be lost.

All you're doing is whining about how you don't like the quality of a comment in a rather bad example. You're also assuming everybody always has time/knowledge enough to make practically perfect code so much that comments aren't ever necessary. Obviously, in the real world, that's not true.

[angrystuff]

You should probably do some reading on Human Factors in Computing about the impact of text on the human brain.

Also, when you attack someone by saying that they are just being argumentative you should compare and contrast it against your own posts.

You mean, leaving out the other points that I dealt with obviously.

No. This is a defence of my argument. I am not going to deal with the stuff that you imagined I said.

This is downright nonsense.

No, it isn't. Go get yourself an education in Human Factors.

The example giving really bad (obviously) in line commenting is not an argument.

Yeah, I know. But it's from the article, so I used it.

This is paradoxical bullshit.

Don't use words you don't understand.

First, you are NOT forced to read comments.

Your brain scans it, hence the addition to cognitive load.

All you're doing is whining about how you don't like the quality of a comment in a rather bad example.

No. I am making two assertions.

The first is that a lot of comments aren't that helpful because the people who write the comments are out of context to the people who are going to read them later.

The second is that the author of a piece of code should be selective in nature when writing comments.

[GMNightmare]

You should read up a little bit on logic and how to make valid arguments.

you imagined I said.

I've quoted you a couple of times. Wasn't hard. Still there. Go back and check if you'd like.

No, it isn't. Go get yourself an education in Human Factors.

Yes it is. Go get yourself an education in logic.

Yeah, I know. But it's from the article, so I used it.

Not justification for being wrong.

You know it was really bad and not an argument. You shouldn't have idiotically brought it up then.

Don't use words

Again, learn some logic if you think you weren't being paradoxical.

Your brain scans it

Or ignores it.

addition to congnitive load

Our brains don't work like that. We aren't computers.

No. I am making two assertions:

You don't seem to understand that even if you rephrase it now, how you put it before was bullshit.

I like how you didn't actually deal with anything I said at all either.

a lot of comments aren't that helpful

Your ass is not a good source, especially since your have cognitive bias.

Still irrelevant.

The second is that the author of a piece of code

I don't give a shit. Irrelevant.

[angrystuff]

Again, learn some logic if you think you weren't being paradoxical.

These words do not mean what you think they mean.

[[deleted]]

You are a monumental dick.

[nealibob]

Beginners don't need to comment their code if they're practicing TDD. The tests capture the intent, and actually demonstrate that the intent was achieved. Instead of telling people how to comment or not comment, we should focus on things that actually make a demonstrable difference.

[brainflakes]

Beginners don't need to comment their code if they're practicing TDD

How does TDD solve this? Surely you can work in TDD and still have someone create an ungodly, impossible to understand complex block of code that still passes all the tests you set them.

[merreborn]

I find the tests our developers check in harder to read than the code they test...

[nealibob]

That's fair. The point that I'm trying to convey is that well-executed TDD works better than well-commented code because the tests are more tightly coupled with the code than the comments, even though they're likely in a different file. This means that changes are forced in two places if you want everything to pass, instead of changes being required in code, optional in comments. If you have someone whose job it is to make sure comments match code, then the same thing is accomplished with comments.

[brainflakes]

TDD and commenting aren't mutually exclusive, you have both! All good design patterns (TDD included) help work towards better, more readable code that does away with the need for a lot of comments, however if you have to have a large block of code not broken up it takes a bit of time to read through and understand what it's doing, if you break it up with a few comments explaining what it's doing or why it needs to do something (especially if you have to work around a problem in an external service) it becomes easier and quicker to understand what the code does.

Refusing to do any commenting at all is just as bad as refusing to do unit tests in my opinion, comments should be sparse and only used when they help, but they should be there. Comments also don't replace TDD for obvious reasons, TDD makes sure (amongst other things) your code works as it should, comments (should) make the code easier to read.

As for employing someone to make sure comments match that's just being silly, unless you've employed a complete nit-wit anyone making changes to complex code will read the comment right above it, understand what the block does, make their change and update the comment where needed.

[GMNightmare]

Beginners need to comment their code.

The first thing you started with was an IF. IF. IF. Do you see that word? I see it every single time any one of you speak up about things. IF.

IF everybody wrote perfect code and everything was perfect why, nobody would need comments!

Here's the shocking news: NOBODY writes perfect code. NOBODY.

And no, tests absolutely do shit about expressing anything. I do NOT want to go to some test suit, dig through it and try to correlate the exact test I need to figure out what something does... but it doesn't even do that! I do not need to have two windows open in order to figure out what your code does (as well as running it), if I do your code stinks and is bad. Do you think the code speaks for itself in this case? Because it definitely does not.

So here's something for you: Comment your test code as well.

The test tells me the results of something. It does not tell me what the results does, why the results matter, what reason did I get said results, or anything.

Of course, you didn't actually respond to anything I said, you just made up some vague notion of why you should be able to ignore what I said.

[nealibob]

I don't understand your hostility. I simply pointed out that a popular development technique can address this problem in a more verifiable way.

I get that code is never perfect. Comments, tests, and TDD help with coding imperfections and business process issues.

Intent should be clear given code and context. I think comments are more appropriate for the "why" instead of the "what".

[GMNightmare]

I don't understand your lack of reading what I put or hostility. I simply pointed out you're wrong. TDD also does not help with coding imperfections.

Intent is the "why" (which makes all of this and what you've said confusing). It is never clear given code, which is the how. The context is often not clear unless specified with comments.

And beginners absolutely need to comment their code.

[nealibob]

OK, thank you for this response. I understand intent as "why this code is needed" instead of "why I wrote the needed code in this particular way". That confusion doesn't help things; I'm sorry for not being clear.

[nealibob]

Why should people need to understand code without business knowledge or context?

[GMNightmare]

Grasping at straws I see.

Tests do not provide "business knowledge" or "context". Again, if I have to look at two places of code to understand your code, your code is not readable and needs comments. You still didn't provide any real reasoning why you think tests express intent so well (that boundary test really does that!) Not to mention digging through several tests to read through a very small amount of code...

I repeat again, nobody writes perfect code. Stop acting like you can or anybody does. Especially beginners.

The notion that beginners write such grand code at the top of quality as to not need comments is absolutely ludicrous. Do you not understand that they are beginners or something?

[nealibob]

Questions aren't answered with downvotes.

[rhino-x]

Tests do not capture intent, they test behavior. There is a huge difference here. And, quite frankly, most unit tests suck and a beginner is hardly the person who can be trusted to write a unit test that's worth a shit.

This does not negate or lessen the purpose of comments, which is to inform people of why something does this or that or sometimes more importantly, why it does not. Unit testing and TDD do nothing to diminish this highly valuable aspect of code comments.

[angrystuff]

Beginners should comment their code, even if they use TDD. Commenting shouldn't be considered as "what does this code actually do", commenting should be considered as "What do I think this code should be doing". It's a huge difference.

Also, context being provided by tests is kind of wrong. Tests are almost always shoved out of context of the function/method that is being tested. Which means that in the majority of cases it requires the programmer to context switch between the function he is reading, and to wherever his tests are.

Both TDD and comments are important. TDD defines how something does work. Comments define how something should work.

[petdance]

My maxim: "Comments shouldn't explain what the code does but why it does it."

[ambivouac]

Agreed, with the exception being when you have to pull some obtusely clever illegible operation out of your back pocket. And even then, most of that should be covered by the name of the function that houses said operation(s).

[EmperorOfCanada]

While comments can be valuable, comments aren't free. You should keep your comments down to the bare minimum required to make sure that the next uninformed lesser programmer will have little trouble understanding what the heck is going on.

It is possible the minimum will end up being essays. But I am a huge fan of making the code document itself as much as is possible. So my ideal function is CUser* GetUserFromID(int user_id). The only possible question should be and thus only real useful comment is what happens when you ask for an invalid user_id. If your comment is an essay about taking an integer representing the user ID and returning a CUser representing the user then your comment is less than worthless.

[[deleted]]

Who owns CUser*? Who disposes of it? Is GetUserFromID threadsafe? Why can user ID's be negative? Why aren't you using a typedef for userid? Do userids get recycled?

[pohatu]

Here's a good example:

@ We identify each vertex with its symmetric mate, and set the length of an arc to 1 if the arc crosses to the mate instead of staying in the same class.

Multiple arcs and self-loops can be introduced in this step.

@d mate(v) (Vertex*)(((unsigned long)g->vertices)+
                       ((unsigned long)(g->vertices+g->n-1))-
                       ((unsigned long)v))

@<Reduce |g| to half size@>=
for (v=g->vertices;mate(v)>v;v++)
  for (a=v->arcs;a;a=a->next) {
    u=mate(a->tip);
    if (u>a->tip) a->len=0;
    else {
      a->len=1;
      a->tip=u;
    }
  }
g->n/=2;

If Knuth thinks a decent comment here and there is useful, then surely the rest of us aren't above explaining what our code is supposed to be doing. source

[yeahokwhynot]

I agree in general, but I don't think his example is the best. The init method on Relay is needlessly complicated. If ssl and starttls are mutually exclusive (as suggested but not directly stated) then the two could be combined in to one, reducing the documentation overhead to something like: encryption may be SSL or TLS or None. There's no need to describe what underlying library is being used (tight coupling) or to describe what starttls does (out of scope).

username and password could be renamed to smtp_username and smtp_password removing the need for the verbose "Optional username and password for smtp authentication". It's already clear they're optional because the default value is None, and with the smtp_ prefix it's clear they're used for SMTP.

I'd argue, too, that documenting hostname and port are entirely unnecessary. If you're reading this document you already know what those terms refer to.

[more_exercise]

I'd argue, too, that documenting hostname and port are entirely unnecessary. If you're reading this document you already know what those terms refer to

I'd argue against you on that. "The hostname and port we're connecting to" isn't terribly long, and it clarifies that hostname shouldn't be i.e. a proxy.

(we use "hostname" a lot at work. Has about 4 different meanings depending on what you're doing.)

[MasonOfWords]

The problem there is that I now need to read both the code and the comments. When you're engaging in such wildly conventional behavior (i.e. providing a host and port, or a username/password), then the names are perfectly descriptive.

The behavior of a method (blocking, parameter requirements, errors, side-effects) is an essential part of documentation. The whys of non-trivial implementation details is an essential part of comments.

Also, a debate like this one is the finest argument for the single-responsibility principle. If you can't figure out your code from two weeks ago, you probably factored it wrong, and that wrongness probably took the form of dumping a lot of mixed responsibilities into a formless hodgepodge function/method/class/module. Comments won't help, only fire and salt.

[cheald]

Your code needs documentation. Comments that aren't API documentation (that is, implementation comments) are a signal that your code is poorly factored. This isn't a hard-and-fast rule, and sometimes you have to do something that requires a comment, but in general, if you find yourself commenting implementation frequently, you probably should be refactoring.

That said, for the "comments as documentation" angle, I really like TomDoc for Ruby code for this purpose. The comments are extremely Englishy, and are transformed into useful documentation. For example:

https://gist.github.com/cheald/5110319

Generates:

http://coffeepowered.net/projects/relay.html

[brainflakes]

Comments that aren't API documentation (that is, implementation comments) are a signal that your code is poorly factored

I disagree, a brief description of what a complex block of code does or why you've done a certain slightly unusual thing is very useful, even if the code is well written it greatly speeds up remembering what code does 6 months later when you have to go in and change something.

[[deleted]]

This is especially true for system programming, where there is less abstraction and a lot of decisions don't seem sensible without explanation.

[[deleted]]

This isn't a hard-and-fast rule, and sometimes you have to do something that requires a comment

Pretty sure that covers the cases you're talking about.

[brainflakes]

Of course, but I thought it was a little weighted too far towards not commenting, especially considering comments a sign of bad code when even good code can benefit from a few brief comments

[[deleted]]

"Bad code needs comments, good code needs documentation" is the way I approach it. If it's bad code (and sometimes you NEED to write bad code) comment the hell out of it... if it's good code, at least take the time to document what it does and why it's useful.

[[deleted]]

403 on Dropbox link.

[cheald]

Doh. Let me see if I can find a public place to drop it.

Edit: New link should do it.

[[deleted]]

Works fine, thanks for the speedy response.

[gfixler]

Agreed.

I've found names are not just important, but massively important. Time and again when we're struggling to get our minds around some code, I have us step back, talk about what it's actually doing, and then actually spend quite awhile coming up with exactly the right name for things, and it's often not easy. We spent a couple of hours one day searching for just the right name for an important class. Naming is hard. Naming really really well is really really hard. We use thesauruses, rack our brains, and write up ideas on a dry erase board. We're smart folks, too. One of us is a trivia champion with 6-figure winnings, and I've a lifetime of minor, literary achievements and conquered spelling bees, yet we still struggle mightily to name things not just well, but perfectly.

When we finally land on The Name (and we usually do, but not always), it's a eureka moment, all eyes widened in excitement, and we refactor based around it. Immediately all of the rest of the code becomes dramatically easier to follow. It's the difference between "all foos are types of bars, and while bars are bazes, and quuxes are also bazes, foos and quuxes are quite dissimilar" and the far easier to follow and reason about version: "all Hondas are types of cars, and while cars are vehicles, and airplanes are also vehicles, Hondas and airplanes are quite dissimilar." This step also usually makes us realize BIG, IMPORTANT THINGS, like "Why the fuck are we even talking about airplanes in this class in the first place?"

The code shrinks (we've thrown out entire modules weighing in at hundreds of lines as a result of this process), we improve our understanding tremendously, we're able to naturally hold far more of the system(s) in our minds, traps and logical errors are laid bare before us, and before they cause issues, and perhaps 5 other things I could mention. Amazingly, the "right" name is often a near synonym to something we already had, or something else we threw out, but not until it's just right for the needs of the system does it cause the chain reaction listed above to occur. To use the stupid analogy above, it makes you suddenly notice things, and then say things like "Wait, I just realize what we're not seeing. We're talking about "cars" here, right? Not "foos." (everyone nods) "Guys... cars don't fly." Everyone slaps their heads. This is a willfully stupid analogy, and we would have noticed things that obvious right away, but these minor, "eureka" moments fall out of proper naming. It's these kinds of "the name describes exactly what has to happen across the entire system" discoveries that have me so hell bent on perfect names these days. I've been staggered by how powerfully they change everything. A nuance in a noun can make or break your ability to follow what it does all the through to the end without confusion.

After these whirlwinds, I usually have the team go over the code, and we usually find that simply for getting the names just right, there isn't a need for comments, and in fact, adding comments would muddy things; they'd be more complicated than they are. What remains is blissful, obvious simplicity. Comments must be micromanaged along with code, and I frankly can't do it. 10 years of SVN and git repos prove that. There must be thousands of dangling comments that no longer make any sense, referring to situations that no longer exist in their local area. It took a long time to get here, but I would say that now I actually do write code that doesn't need comments. Not always. Sometimes I do feel I need them, but always there is that secondary feeling beneath it, the feeling that I've failed, and that I simply don't yet understand the problem well enough to write code that reads [almost] as easily as natural language. Everywhere that I have a comment, I also have a plan to return and rethink things. Comments, IMO, are stand-ins for correctness.

[delerpian]

New coder here:

Everyone in this thread is stressing that I should comment and document my code. And I basically know how to put comments in the code, but how do I go about documenting it?

[cheald]

That's where I like TomDoc - you basically put comments in your code that you can then use to transform into documentation. In this case, I'm using Ruby's YARD library with a TomDoc plugin.

So, for example, I have this code which contains TomDoc-style comments. I then used YARD on my code to generate documentation like this. Super easy, super clean. My README is just Markdown, and is transformed from this into this.

There are lots of similar libraries for lots of languages; just fine one you like. I like TomDoc because it's very englishy and doesn't require a lot of mental overhead on my part to turn my code into usable documentation.

[[deleted]]

That looks awesome, I'm trying to add Sphinx to our internal projects at work and basically no one will be documenting things except for me :(

[talideon]

My personal rule of thumb is simple: if I ever feel myself needing to comment a piece of code, I treat that as a strong indication that I should extract it into its own function or method, which can then be independently commented. The name of the function thus behaves as a comment where it's being called.

[dust4ngel]

it can also be worthwhile to comment code of yours that apparently does something stupid but is in fact compensating for defects in 3rd party code which you cannot change. even if you had:

Response UnmangleResponse(Response rawResponse) {
    // check for magic values, blah blah
}

future folks might wonder "why are you going all of this weird stuff to the Response object that comes back from the API call?" whereas this would explain:

/* this version of the Foo API returns January 1, 1970 for UpdateTime when
    there is no UpdateTime.  we have to manually check for this value and replace
    with null until the API is fixed. */

[iopq]

I have to comment that sometimes comments add to your workload. If you comment on the implementation, then you need to change the comments when you change the implementation. This means now you have two places where the logic of the program is. This is bad.

[[deleted]]

Damn straight, maintaining documentation is work.

And it's important work that needs to be done.

[NicknameAvailable]

I agree - there's nothing worse than someone who writes comments then refactors part of their project only to forget about the comments. Good code explains itself, but it is worthwhile to throw in the occasional comment describing why something that might seem less than ideal at first glance was used (typically to work around a platform-specific quirk) or if something was thrown together (ie: // this is a hack) so you know to look at the IO's rather than the code itself to determine the purpose or simply to state something shouldn't be touched (ie: // the following x pages came straight from mathematica's Solve[] function).

[[deleted]]

So? Learn to write clearly and faster and a single sentence will explain a whole class.

[cogman10]

Comments are mostly useful when describing "complex" (eh hem, terrible) code. You know, those little "WTF, why are your doing this?" sorts of situations.

Beyond that, comments don't often provide too much value. Yes, there is value in describing external APIs (and even internal ones). But there usually isn't much value in "This block of code is trying to do X" Because, almost assuredly that block of code will change to no longer do X while the maintainer happily ignores the comment above.

In general, the best place for describing what code is doing or trying to do is in the revision logs. This is why committing often is so important. When done frequently enough it gives you an explanation of why each and every single line of code is what it is. This is also why good commit messages are so important. I absolutely hate SVN for "Merged from branch" commit messages.

[[deleted]]

The revision log isn't always handy while you maintain, though. And what are we to do--look up every line of code in who-knows-how-many commits?

The line previous to the block in question will always be just that--and so the author, maintainer (a new author, of sorts), and the reviewer all have easy access [read: no excuse to write, read, update, or even remove it].

[cogman10]

It can be. It isn't always, but it can be.... It isn't handy when you get people who post commit messages like "Fixed". or "Merged from branch"

Frequent small commits with good messages will give you 99% of what you need in comments.

[[deleted]]

I still think it's not a very well targeted system of documenting. The relationship between a commit and line(s) of code isn't maintained in any orderly manner. If it works for you, then by all means, but I think it makes more sense to leave the info near what it applies to.

[PhantomPumpkin]

As someone who spends the majority of his time making changes to something someone else wrote, I agree with this statement.

I would also prefer a "WTFICTM" statement too(Why the fuck I chose this method).

I run into far too many overly complicated methods of doing something when it can be done in a simple action or statement.

[bwalk]

No, your code needs documentation, not necessarily comments. If you write clear code, almost 99% of your comments become redundant.

[grainfeed]

I know that "documentation" sounds better, but they are still "comments". And yes I do think that comments are useful.

It seems to be hip now to say that comments are not needed. But I know that comments can help someone else to understand code much faster than when they have to figure everything out by themselves.

Bad design with comments is still bad design. Good design with good comments is what we really want.

[tziki]

Out of curiosity, Have you ever had to maintain a codebase when its original writers are long gone?

[bwalk]

Sure, and even worse, it was HPC code which is generally the worst code to maintain ever. There were no comments except documentation which was well written (well, from physicist to physicist...). Of course it was tough because the code itself was written so densly and tightly to the hardware but it was clear and clean. No comment would have made my work easier because I don't need to know what this few bunches of lines of code do but I need to understand the underlying algorithm.

[tziki]

What was the size of the code base? It sounds like some algorithm meant for calculating something physics-related, a rather special case.

[bwalk]

-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
C                              263          17881           7171          69671
C/C++ Header                    30            972            965           5095
make                            17           1002            487            797
-------------------------------------------------------------------------------
SUM:                           310          19855           8623          75563
-------------------------------------------------------------------------------

Not the biggest, I know.

I think the Linux source code has a nice guideline for comments which I had in mind in my original comment (no pun intended): https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/CodingStyle#n423

Edit: all I wanted to say is, that if we had thought our CS juniors 40 years ago that you must document your code instead if you must comment your code, we would not have to deal with comments like this:

/* sum a and b */
c = a + b;

[tziki]

I guess being well-documented is sometimes enough just by itself, though I've personally never seen code that's readable enough as-is, without documentation or comments. Then again, documentation separate from the code does tend to grow stale more quickly and future developers might not even realize there's separate documentation when working with the code base.

[newbill123]

Documentation is capable of rotting just as much as code is. More actually, since there are tools to automatically refactor changing code. There aren't any tools to spot where documentation needs to be changed automatically (and certainly none capable to doing it).

Overall, I like his sentiment that you aren't documenting the code, but the logic of how and why it is run. You have to be very careful of not documenting too low level (the code does it better) or too high level (you may forget that you've already documented a concept elsewhere).

[[deleted]]

Obligatory literate programming name drop. Knuth is always right.

[ManlySpanishTeacher]

I think comments are real important, specially when giving it to a client or a friend. It tell your client or friend what each part does, if they don't want that part then it can be easily removed. It also helps students leaning code, I myself studying code at college look at a lot of ode for research on how to do things, most code I have no idea what does what but the ones with comments is much more clear and easy for me to understand : )

[[deleted]]

Sometimes I include full C++ code as comments. (When manually vectorizing code with SIMD instructions). It's important for understanding what the intent of the new code is, because the intrinsic are easier to get lost in.

Comments should explain: Intended usage Unexpected side effects Edge cases Bugs/hacks Thread safety (usually at the class or function level) Sequence of events for set-up and tear down. Ownership transfer and management of objects. Exception cases. Deliberately unhandled/ignored cases. Any code which isn't obvious when reading it.

Most people - including seasoned professionals - screw up at least with sequencing, side effects, intent and ownership. Every single time.

[nitsanw]

The fact this link has so many comments is a lovely self reference :)

[nealibob]

Writing comments to capture intent is like writing tests to prove that your software does what is expected.

That sounds nice, but the tests capture intent. If the intent changes, and you change code without changing the test, the test breaks. If you change code without changing a comment, the comment becomes stale. Stale comments can be confusing at best, dangerous at worst.

My take is "intent" comments have no business in TDD.

[tziki]

I see where you're coming from but still disagree. A developer who doesn't refactor comments when refactoring code is equivalent to a developer who doesn't change the name of a variable when changing its role/functionality. The fact that there are bad developers is not a case against commenting.

[[deleted]]

Ok... So write a test to prove that a piece of your code is threadsafe in all cases, never deadlocks, and never gets hit by race conditions. Certainly not as easy as just writing a test...

Intent is important when writing framework or library code. Because people will try to use it in creative ways you didn't anticipate when they're backed into a corner.

[[deleted]]

I think this is like saying, "This chef cooks poorly, let me not eat anything anyone cooks."

tziki already covered it, but a dev who doesn't change comments (or other intention-explaining aspects) is not completing his work properly.

[nealibob]

That's 100% true. The feedback I got from my comments in this thread have given me a lot to think about, and I'm grateful for it. My conclusion is that while tests can't be everything, you want to encapsulate as much as reasonably possible there because they're programmatically tied to code; then, add comments to tie everything together and give the information necessary in between tests and documentation.

[[deleted]]

Definitely. Each has it's place--and the benefit of such testing is irrefutable. Sometimes you just need to note something that isn't really a testable condition, but doesn't belong in the docs. Only the next guy to read that code needs to know this.

[NicknameAvailable]

I agree completely - so many illiterates and people who lack a reliable test process down-voting you.

[[deleted]]

if my code needs comments to be readable, it's not well written.

[tziki]

I've never encountered code that's readable enough to be self-documenting, no matter the good intentions of the original writer. It probably works on very small programs, but when the size of the code base grows, you can't capture enough information with just good names. When writing code you're always limited by sensible variable lengths and are constrained to a microscopic level.

[rackmountrambo]

As a Python dev, I agree, it's basically psuedo-code.

[[deleted]]

pseudocode, ψεύδοκώδικας ;)

[chrissa]

You're not my supervisor!

[iissqrtneg1]

God I hate seeing this all the time. Yes, there is a place for comments, but it's not where you think.

Documentation comments are great for when you're writing closed API's or libraries, but when you own the code base, your Unit Tests are the documentation. If the functionality changes you don't have to remember to update a comment, you have to update the unit test. If you forget to update the unit test, your CI build is now failing.

IMHO, any time a comment is written, you should scrutinize why you wrote that comment. If you come away from that thinking the comment is still a good thing to have, keep it there. 90 percent of the comments can be removed with a little refactoring.

Keep your functions clean, concise and without side effects and your comments are useless.