[recycleme]

I've met a few senior level programmers who frown on detailed commenting (or commenting at all). I cannot wrap my head around this since I consider it best practice to comment.

A reason given to me was that "it takes up too much time to comment and when you make a code change you need to make a change in the comments as well." To that I say, so what! I would like the future me (or the future programmer) to have full knowledge on what's going on in the code.

[flatline3]

> I've met a few senior level programmers who frown on detailed commenting (or commenting at all).

If they express those views, I wouldn't call them senior.

Commenting is necessary to express invariants, and to summarize complexity that would otherwise require each reader of the code to understand the code itself in depth.

Those are actually closely related things.

Very few languages are capable of succinctly expressing sufficiently detailed invariants. Some are better than others -- maybe they support Maybe monads instead instead of possibly-NULLs. However, it's rarely possible to express -- purely in code -- what the code is supposed to do, what the input is supposed to be, and what the output is supposed to be.

Failing to express those things means that any future reader/maintainer will be forced to trace your code, in its entirety, to reverse-engineer how it is probably supposed to work. In many cases said maintainer can never know for sure without tracing your code and ALL code that calls your code -- otherwise, any change to that code could break undocumented behavior that other code relies upon.

Anyone who advocates against comments is justifying laziness, and they're wrong. The only supportable argument for not commenting is if a language is sufficiently powerful and succinct enough to express all the invariants normally expressed through comments, as well as being readable enough to permit a future maintainer to understand the design of the code without requiring them to spend an undue amount of time studying its inner mechanics.

I'm not aware of such a programming language.

[rimantas]

  “Don’t comment bad code—rewrite it.”
  —Brian W. Kernighan and P. J. Plaugher

Is that senior enough for you?

  > Anyone who advocates against comments is justifying
  > laziness, and they're wrong

No, they are actually advocating to put more effort in thinking about stuff: how you name your functions/methods/whatever, how do you name your arguments/parameters, how do you write the code itself.

To anyone interested I recommend to get a copy of "Clean Code" and read the relevant chapter. IIRC "Code Complete" mostly agrees.

[flatline3]

> Is that senior enough for you?

No. Have you read 70s and 80s C code? Tried tracing through the original UNIX kernel sources? Tried working with them?

To understand all the invariants of one small aspect of the system quite often requires tracing through the whole system until you get to a well-documented input/output module point (via comments, man pages, or otherwise).

Also, the quote (aside from it being out of context) says to not comment bad code.

> No, they are actually advocating to put more effort in thinking about stuff: how you name your functions/methods/whatever, how do you name your arguments/parameters, how do you write the code itself.

You can't define all the invariants -- or summarize for readability -- in pure code.

[ori_b]

> No. Have you read 70s and 80s C code? Tried tracing through the original UNIX kernel sources? Tried working with them?

Yes. It's some of the easiest to understand code I've read. For example, http://unixarchive.cn-k.de/PDP-11/Trees/V6/usr/sys/ken/slp.c

They're actually quite decently commented. The functions describe what they do clearly, and the bodies show how they do it tersely, with comments around the sticky bits.

Have you read through the original Unix kernel sources? Claiming that they're uncommented and difficult to work with is surprising. (On the other hand, the directory structure could be better.)

[flatline3]

Without tracing the backing kernel structures and the code that relies on them, please describe why sleep(chan, pri) works, and as a maintainer, what I need to watch out for when modifying that code.

What does swtch() do? What does issig() do? Does that mean it's checking for a signal during sleep? What signals could be generated? Under what circumstances do I need to check for those signals? Are there any race conditions? Does ordering matter? What happens if I move the call to issig?

Beyond the invariants, this code is NOT READABLE. I can't just glance at the comments for an atomic unit of 4-5 LoC and see what it does -- I have to examine the code in depth, running the logic in my head, and explore the workings that way.

Reading code without comments is like tracing out a circuit without a schematic or documentation. First you have to manually establish the what, and only then can you even start to spend your time determining the why.

I work on modern BSD code. It's better than this old stuff, and I still have to dig to figure out how/why things are supposed to work. It's a headache compared to properly commented and documented code, where I can just skim standalone units and know what they do without having to trace everything myself.

[ori_b]

Of course you need context to understand code. You can't get away from that without essentially translating the rest of the code into prose and attaching it to each line. At which point there are enough comments that you need context to figure out which parts of them you care about, reading them becomes a chore, and they essentially become noise. I've seen codebases with insane levels of commenting. I found myself ignoring the comments and tracing through the code.

If the model is simple and the code is clear, learning the context becomes easy, and it fits into your head. Following code becomes easy.

[slurgfest]

That code you linked has lots of comments containing lots of information. How is this an example of how Senior Programmers are against comments?

[qntm]

Maybe I haven't read K&R carefully enough but how can you have a function declaration like

    sleep(chan, pri)

without any data types?

[alexfoo]

Because the default datatype is int:-

  $ cat z.c
  foo( a, b )
  {
          return( a+b );
  }
  
  main( void )
  {
          return( foo( 3, 4 ) );
  }
  $ gcc z.c
  $ ./a.out
  $ echo $?
  7

[crpatino]

Since you have already dismissed a well thought response, let's try irony instead:

"When you have spoiled ingredients, dispose 'em. Do not try to cover the bad flavor with condiments." - Famous Master Chef.

"You see? Master Chef does not like condiments. They take away the natural flavor of the food and anyone who uses them is an idiot who never will be a true cook". - Zealot Wannabe.

[einhverfr]

Actually the people I have met who tend to be most against documenting what code does with comments tend to have the best commented codebases I have ever seen.

[crpatino]

You never specified that your backslash referred exclusively to comments that document what the code does. This kind of comments are in most cases the result of bad habits taught by introductory programming books and instructors alike, with possible one exception [1].

But comments are incredibly useful to document why code exists in the first place, what are the assumptions that must hold for it to behave as expected (including but not limited to preconditions, invariants and post-conditions), and possibly how to use it (if you are using some utility like javadoc to generate other types of documentation from source code).

[1] The exception I am thinking about is that in real life you cannot always deliver the best quality possible in your projects. You have to interact with horrible systems, make ugly tradeoffs and meet deadlines with limited resources. Things get convoluted from times to times, so the best you can hope for is to leave thoughtful comments explaining how some specially hairy component works. The maintainers of that software (including a potential future version of yourself) will be very grateful for this.

[einhverfr]

Agreed on this point. The idea is that the comments should have something to say apart from the code. You don't put a footnote in a book to repeat what you just said. You put one in to add a reference to something else, explain a caveat, or otherwise say something useful out-of-band.

In general, in my experience, the people who are most hostile to willy-nilly comments have some of the best commented code. They see the code as written both for the computer and the programmer, and the comments are thus either interface promises, or are footnotes. Most of the people like this I have worked with tend to produce extraordinarily readable code which contains a good number of comments which should be there. But the worst codebases I have worked with hands-down are full of comments.

As for your exception, I agree. I think it's worth flagging such comments however so that the reader immediately knows that this is a special clarification.

The last time I described what my code did, I was using Perl 5.6 or something and was trying to do a method call to a fixed name in a variable package and was having a horrible time. I ended up, I think, using the symbol table directly and the syntax was worse than hairy. It was downright misleading. So I added a comment something like:

# HELP! I can't find a better way to write this. The syntax is .... Anyone have any suggestions?

If you understand you are writing for a human audience and that your comments will be read only if generally useful, then the this leads to both code clarity and comment clarity. It may not always be possible to maintain and hence one would add comments explaining tradeoffs or flagging a section as unclear (and possibly explaining it). But these are avoided as best one can.

[anthonyb]

> “Don’t comment bad code—rewrite it.”

That's advocating against bad code, and specifically the fairly widespread practice of commenting what it does rather than fixing it.

It's not a blanket statement against comments in general.

[einhverfr]

Kernigan is absolutely right here btw.

There are so many problems with trying to make up for unclear code in comments, that's a real losing battle. I recognize that it may be worth breaking that rule sometimes, but then it is worth noting that, and flagging it so that other programmers can see and fix it. A comment like "#FIXME: This code is unclear: What it does is...." is perfectly acceptable.

Comments are for collaboration. You do NOT want to make them even appear useful for debugging.

[randomdata]

> that would otherwise require each reader of the code to understand the code itself in depth.

Is that a problem? Even in code that has good comments, I always skip the comments and go straight for the code. Comments are okay if the code needed to employ hacks for some good reason, but otherwise I've never met a function that I wish had them.

I often wonder if people come from different backgrounds, which leads to completely different points of view on the matter. Personally, I find code easier to read than natural languages, but that doesn't mean everyone is the same and I respect that you might find comments useful. But why then assume that everyone needs comments?

[barrkel]

Wait until you start working on multi-million line systems in companies where nobody - and I mean nobody - understands everything, and the original authors of pretty much every subsystem has since left the company; and you need to fix 20 critical bugs in the last week before the thing ships. Clues that are more high-level than the code can ever be start being really helpful.

[mattdeboard]

> I've never met a function that I wish had [comments]

Come on, this is stretching credulity. Either that or you don't value your own time.

[einhverfr]

First, I think that requiring the reader to know the code in depth is a good thing. Comments should not be used to avoid this. Comments can decay in relevancy and, aside from function API documentation, should not be used in debugging. The way comments should be used is:

1) API documentation says this: does the code conform? If not, either the specification is bad or the code is bad.

2) Comments inform collaboration, but do not inform debugging other than as API documentation.

[randomdata]

I do agree that there is merit to documenting public interfaces, but there are tools designed specifically for that job so that you do not have to go slogging through the source code at all when you want to look up a definition.

As a result, I feel that is a different matter to commenting for the purposes of code maintainability, which is what the parent poster is speaking to.

[einhverfr]

We are probably on the same page. I wrote this:

http://ledgersmbdev.blogspot.com/2012/08/patterns-and-anti-p...

Comments are not for maintainability.

[flatline3]

> Is that a problem?

Yes, because it means I might need to read 6 layers of code and wind through multiple modules, instead of just reading the top layer that defines the invariants of input/output for a module.

[overcyn]

I don't think people here are against commenting APIs... That's more of a documentation thing.

[einhverfr]

It's not just a documentation thing.

When you document an API you make a promise to the programmer. If you use the API according to the documentation, the API will behave according to the documentation. Documentation of API's establishes interfaces. If the code doesn't conform to the comments describing the API, it is the code's fault not the comments' fault.

I don't think people here are even against commenting code. I think people here are against (and for good reason!) duplicating coding logic in comments designed to describe in line-by-line detail the code that should have been readable in the first place.

Comments like that are FAR worse than no comments at all. If there are no comments at all, a new comment that is clear and relevant will be read. If you have a codebase full of bad comments you cannot start adding good comments until you clean that up.

[jasonlotito]

> If they express those views, I wouldn't call them senior.

I wouldn't be so hasty as to assume that anyone making the above claim should be taken literally. Indeed, frowning on detailed commenting (or commenting at all) seems more like hyperbole then anything. After all, what is "detailed commenting"? It's not indication of quality.

    // Increments x by 1
    x++;

That is a detailed comment, but hardly worth while.

And the commenting at all remark does not indicate that all commenting is to be avoided. Rather that comments should be scrutinized. After all, comments are indicative of a confusion. If your code requires a comment to explain itself, maybe it's best to review what you are doing, and work to avoid confusion.

> it's rarely possible to express -- purely in code -- what the code is supposed to do, what the input is supposed to be, and what the output is supposed to be.

It's actually fairly easy to do that in all languages I'm aware of. It's part of the reason you have Unit Tests. To document what the code can do, but also the expected input and output. More often than not, we forget that.

I dislike the idea of promoting comments for the sake of comments. I much prefer the push for clarity in code. Limiting clarity to comments is bad form, and generally those pushing for lots of comments excuse confusing code because they use comments freely. They also believe that these comments will remain relevant, and make the call that should they not, it's not their problem, but the programmer that fails to update the comment.

This is akin to blocking user out of an account after the first wrong password entered. It's their mistake, after all. And our jobs as programmers are not write robust code. Comments cannot (and should not) affect that code, and relying on comments to provide the quality missing from the code is lazy.

[flatline3]

Unit tests validate invariants, but they don't express them in a concise form, and they're not a suitable form of documentation.

[jasonlotito]

> Unit tests validate invariants, but they don't express them in a concise form

I'd be more in line to say that if your Unit Tests aren't concise, then it's a problem with your Unit Tests, or at least, your implementation.

> and they're not a suitable form of documentation

Well, the output that you can generate form unit tests can easily be documentation, explaining in great detail exactly what can be done with what is being tested, without any hand waving either.

Still, that doesn't take away from everything else I said. In the end, if you rely on comments to explain your code, your code is probably lacking.

[buffportion]

> Anyone who advocates against comments is justifying laziness

That is a gross generalization. I do not, in general, comment my code (and I know and work with many other programmers who do not) but I go to great lengths to ensure that my code is easily understandable. Commenting is not the only way to communicate intent.

I suspect we work in different sections of the industry, but in my world, comments are often a red flag rather than a welcoming sight!

[flatline3]

> That is a gross generalization. I do not, in general, comment my code (and I know and work with many other programmers who do not) but I go to great lengths to ensure that my code is easily understandable.

You're almost certainly not succeeding, because unless you work with a language far more expressive than one I've seen previously, then your code can not express all the information I need to work on your code.

A complete lack of comments is on my top three list of "bad times ahead" warning signs when I inherit a codebase.

The other "bad times" warning flags are:

* A lack of documentation

* A lack of automated tests (integration, unit, or otherwise).

These three things can make or break maintainability on their own, and they also often serve as a proxy indicator for just how much thought an engineer put into fully understanding the invariants and edge-cases of the code they've written.

The hard part of writing comments, documentation, and tests is in understanding invariants and edge-cases. The easy part is writing down what you've understood.

> I suspect we work in different sections of the industry, but in my world, comments are often a red flag rather than a welcoming sight!

Unless your section of the industry has no interest whatsoever in maintainability, I'm not sure our respective sections are very different.

[buffportion]

>You're almost certainly not succeeding

You seem pretty convinced, so I don't have high hopes of changing your mind with a post on an internet forum, but in my experience most comments can be replaced by clearer names, better abstractions and better tests. The ones that can't tend to be about the "why" rather than the "what".

>Unless your section of the industry has no interest whatsoever in maintainability[...]

My primary motivation is maintainability, and your claims to the contrary come across as pretty condescending.

[flatline3]

> My primary motivation is maintainability, and your claims to the contrary come across as pretty condescending.

It's simple frustration with ego-based arguments from programmers that ultimately results in poor code bases.

Ego-based programming arguments are predicated on the idea that those that fail to deliver clarity must simply not be smart, wise enough, or skilled enough -- whereas with just a sufficient level of intelligence and skill and wisdom, one can produce lofty, comprehensible, elegant code.

If there's one constant I've found in my career, it's that everyone is dumber than they think, and everyone screws up. The ONLY thing that produces high quality code is careful attention to detail and slavish devotion to documenting and testing.

It's no different than any other pursuit; even a master carpenter will draw up plans, follow them, and measure twice (or three times). To think that one is smart enough to write perfectly literate code is foolish, and to force your future maintainers to deal with your uncommented code is to foist the costs of your short-term decisions onto them.

[einhverfr]

Comments in the body of a function should never be necessary for maintenance. The most unmaintainable code I have ever had the displeasure of working with was code which either had no comments or documentation or code with sparse documentation and LOTS of code comments.

If comments are necessary for maintainability, a simple solution is to flag the comment with a FIXME tag so that the next guy reads the comment and realizes that a section of code is unclear and should be looked at with extra care.

That isn't to say I am against code commenting. I find that when I follow my own code commenting practices and try hard to avoid using comments to explain code, I still use them frequently, probably more frequently than average. I am just saying the purpose needs to be clearly thought out.

In my view, the most important thing is interface documentation. This is a promise to the programmer, and it forms the basis of what you might think of as a development contract. You write your code this way, call the function this way, and you will get a certain return result. To a maintenance programmer, then, the question is whether the code works and by "works" I mean whether it fulfils its part of the contract by implementing what the comments promise. If a caller is requiring a corner case, then that can either be added to the documenting comments (i.e. adding to the promise) or the caller can be changed. So these comments are of vital importance and I see nobody arguing against them.

But within a function body things are different. Comments can be helpful here for collaboration and future development (and a subset of this is maintenance, but if you mind the rest this will take care of itself). A good maintenance programmer knows when to read the comments. if the comments describe the code, a good maintenance programmer will ignore them all in order to focus on what the code is actually doing and whether it fits the API docs. Bad comments then hurt more than they help and this includes comments which needlessly describe what the code is doing.

On the other hand good comments are golden and these either flag potential issues for the programmer (# BE CAREFUL OF SQL INJECTION HERE BECAUSE WE CAN'T USE PARAMETERIZED QUERIES!) organize code (# variable declarations) or add footnotes so that it is clear why a given choice was made (# RFC XYZ specifies a max timeout of 120 seconds).

The hostility is not to comments in code. The hostility is to a certain common practice, whereby comments duplicate code. There is no case where this makes sense without flagging the issue to a future programmer and noting that a rewrite is in order.

[einhverfr]

Well, I inherited a codebase where all comments fell into two groups:

1) Copyright notices and brief (1-2 line!) file-level descriptions at the top of each file and

2) Comments that the code needed to have in place in order to run properly... Delete the comments and things break. I am not kidding.

Oh, no documentation and no unit tests either. We started adding unit tests and found that things like number rounding failed.....

Years later we are still replacing the old code as fast as we can. The obvious things including braindead security issues, were just the absolute tip of the iceberg.

Nowadays I write my documentation first, then code, then at least some tests.

[mangler]

That's why you "Inherit a codebase", as opposed to "Build a codebase". People who maintain and people who build are... well... they're just different people. We do need them both, but, they are different. Which is why we need them both.

[flatline3]

I also build code rather large new products, too.

People that build with no regard for future maintainers are building code incorrectly.

It makes me happy when I hand off a code base and the receiving maintainer actually tells me that they appreciate how clear and understandable it is. That's a level of care I wish I always inherited.

Maintainers versus builders aren't different people -- that's just what intellectually lazy programmers tell themselves when they're making another mess for someone else to clean up.

[einhverfr]

I don't think that is necessarily the case outside a corporate environment. I inherited the SQL-Ledger codebase when we forked to LedgerSMB. Now I am using it as scaffolding to build a very nice, clean, powerful codebase in its place.

[einhverfr]

I do not, in general, comment my code (and I know and work with many other programmers who do not) but I go to great lengths to ensure that my code is easily understandable. Commenting is not the only way to communicate intent.

I agree that commenting is not the only way to communicate intent.

I don't know what you mean by commenting code though. I find in general that the people who treat commenting as a last resort, and look for every other method to clarify code first, tend to also have some of the highest comment to code ratios, as well as the best comments.

This was driven home to me recently when I wrote some PHP classes for interfacing with LedgerSMB. I checked them into github and added the project to Ohloh, and was stunned when it said I had as many comments as code. But virtually all of these were interface documentation.

[jackcviers3]

The problem with commenting code is that code is constantly refactored to deal with new invariants and edge-cases. What starts out as a great way to summarize the purpose and mechanics of a given function or statement becomes immediately stale once the function or statement is changed. In the best case, the comments are revised along with the code they describe.

However, everyone makes mistakes, as you have pointed out, and once a comment is forgotten during refactoring, that comment has become a liability to the future maintenance or use of the code it describes. Given that comments are, by definition, not executable lines of code, commenting errors do not show up in code execution. Since most bugs only become apparent because of incorrect execution, commenting bugs are difficult to spot. This is a problem when developers read the comment instead of the code to discover the purpose and mechanics of the commented function or statement, and can lead to further errors in client code of the function or statement when the called code doesn't conform to the specifications expressed in the comment.

Now the developer who has to fix the code has two things to debug; the code as it is written and the code as it is described in the comment. Which has authority? How do you prove the correctness of a comment?

You can prove the correctness of code, because it can be executed. You can test it using the scientific method, trace its execution paths at runtime and by reading the calling code. You cannot do this with comments.

Additionally, every line of source code is a liability to the maintenance of the code. Each line out source adds computational and mental complexity to the program they describe.

For these reasons, good, verbose variable and function names to describe the what, and corresponding tests to describe the how and why are superior ways to describe code over verbose comments.

However

[einhverfr]

The point of a summary though is to offer the promise of an interface. The code should implement the summary, not the other way around.

Code comments though are different. They are there to annotate code. They are incredibly useful in collaborative environments but only if they are used to organize, discuss, and debate the code, not describe it.

[btilly]

I've just read this whole thread.

flatline3, I can tell you flat out that you are wrong. There are plenty of senior level programmers that are quite deserving of the name who deliberately comment very lightly if at all. There are also plenty of senior level programmers who think that verbose commenting should be required of everyone.

I have experienced both styles, both in forms that are implemented well and implemented poorly. I have read arguments for both sides. I have found that either can work well, and either can work out horribly. (Though attempting both at once is very much not recommended.)

Personally I prefer to work with (and write) code that avoids comments wherever I have any reasonable alternative (clear variable names, calls to descriptively named functions, error checks with error messages that make it clear what I was trying to do, etc). However when all other alternatives fail, I do not hesitate to comment.

The most important case where there is no reasonable alternative is in descriptions of an API. The code that is there is how it happens to work right now. If you want to know what you can rely on to remain true in the future, read the documentation. Anything not documented is not part of the API, and you should be prepared to find it changed in the next release.

[flatline3]

> There are plenty of senior level programmers that are quite deserving of the name who deliberately comment very lightly if at all.

Senior in name (and possibly years) only. I've spent enough years cleaning up messes to know that master programmers:

- Design carefully - Comment liberally - Test thoroughly

Thus they produce clean, well documented, understandable code. Skipping any part of that list is foisting delaying the cost for a much larger later reckoning of some poor future persons.

You might get away without commenting, but you're not doing anyone any favors. Skip all three and you're incurring significant technical debt.

I have no respect for programmers that think their sole job is to write code (no matter how "descriptive" it is).

> The most important case where there is no reasonable alternative is in descriptions of an API. The code that is there is how it happens to work right now. If you want to know what you can rely on to remain true in the future, read the documentation. Anything not documented is not part of the API, and you should be prepared to find it changed in the next release.

All functions are API. Some is mutable, because you can check and modify all callers. Some is immutable, because you can't.

It all needs to be documented, and the cost for not doing so can scale exponentially as a code base grows.

[btilly]

Ah, the "no true Scotsman" fallacy. No matter what someone has accomplished, no matter how much experience they have, you're the judge of whether they are really a senior programmer. And all who do not meet your standards are not senior programmers and are therefore not data points counter to your position.

Read the source code for Arc. You'll find that Paul Graham is not a senior programmer by your definition. Read the source code to some of Damian Conway's modules. You'll find that Damian Conway is not a senior programmer by your definition (though his stuff does usually come with wonderful documentation). There are plenty of other examples of talented programmers in your books are not senior.

From where I sit, I know nothing about you other than your account is about 2 months old and this discussion. In particular I know nothing of what you've done. However people that I respect a heck of a lot more than you have defended very light commenting styles. I've seen it work. I've also seen it fail. Ditto for heavy commenting styles.

Therefore, based on my own experience, I'm going to say that it is complex, with valid arguments on both sides. Which puts me on about the same page as Steve McConnell's book Code Complete.

But I'm going to go further. The downsides of a comment heavy style have to do with the possibilities of the comments being misleading. People have to be very, very careful to maintain comments along with the code. Based on what I've seen, I would personally not trust any team of programmers to do this reliably without having careful code review processes. If you have this careful code review process to alleviate the potential issues with commenting, I would advocate a much heavier commenting style.

But there is one line that is very important that explains a lot of the difference:

It all needs to be documented, and the cost for not doing so can scale exponentially as a code base grows.

There are a lot of problems that scale non-linearly as a code base grows. There are two possible responses to this. The first is to try to create procedures to alleviate the problems that are intrinsic to growing code bases. The other is to maximize what can be done without growing your code base.

There is a fascinating data point on this that is cited in Software Estimation: Demystifying The Black Art. For projects of a fixed size (about 50k lines of code) there is a graph based on real world estimates of months to completion versus team size. Initially as teams grow, calendar months fall. Then the graph bottoms out with teams of 6-8 people. Then it starts to rise. And then falls again. It isn't until you get to teams of about 20 people that calendar months fall to the same level. (Given that lines of code was the measurement, it is likely that the productivity of a 20 person team was overstated.) And then they start to fall further.

If your experience is mostly on teams of 12+ people, your observations about software development will be very, very different than if your experience is mostly on teams of less than 8 people. What works for those types of teams teams is very, very different. And given the huge productivity valley between small teams and large teams, there are a lot of problem areas where the right approach is to maximize what can be done by small teams, rather than to figure out how to build procedures to scale to (the now inevitably necessary) larger teams and code bases.

(If your experience is with larger teams, your first encounter with the potential productivity on small teams can come as a shock.)

[Ralith]

Dependently typed programming languages can do the "express all the invariants" bit. Readability is an open question, though.

[arethuza]

I tend to get a bit upset if code has comments that basically just describe what code is doing rather than why. Stuff along the lines of:

   // Increment the total
   total++;
   // Execute our SQL query 
   var result = query.execute();

Seems to happen a lot with developers who use comments to "sketch out" code (not a bad thing) and then leave the comments in place when the actual code is written.

[MattSayar]

That's a technique Steve McConnell calls "The Pseudocode Programming Process," and while it's verbose, it's not a Bad Thing. I don't do it, but I'd rather have comments like you posted than none at all.

[reddit_clone]

That is legit. I have done it on occasion. It is like a relaxed form of literate programming.

I don't understand this vitriol against all forms of code commenting. (I personally hate the useless, mostly empty function headers forced by some coding standard)

[einhverfr]

The problem has to do with maintaining large, complex, and frequently changing projects. If your code tells me what the program is doing the first thing I have to do when debugging is ignore the comments.

If the comments describe the code this means I have to ignore all comments including those which may be relevant to my debugging. This causes a few specific problems in a collaborative environment.

The first is that the comments get stale/out-of-date/etc, more quickly and are therefore consigned to the archaeology of the program rather than of current relevance. At least with spurious logging, I can take it as a sign that someone had trouble with the code here. With comments I cant even tell if it was done in pseudocode and then translated below. It is useless.

The second is that you can't just add relevant comments into the mess without deleting all the other comments first. Otherwise they can't be sorted out easily or efficiently. In other words, it is worse than useless because it keeps proper, useful comments from being seen or read.

Third, if there are relevant comments there, such as

# This is the maximum value the standard allows for.

Then I won't see these and I am more likely to miss them and hence screw something up by accident.

A better approach is to recognize two things:

1) The code itself needs to be so clear, that you never need any comments for debugging (interface documentation is something very different), and

2) The code plus the documentation together has to be easily readable to the programmer. It also needs to be clear, concise, and avoid duplicating messages any more than needed. Duplication with the documentation of course is required by definition.

I hear a lot of people say they have code they would like to release open source but don't want anyone to see how horrible the code is. The answer is to learn to write code with a dual audience --- human and computer --- in mind. The code comments then function like footnotes would in a text, or as a way for two or three programmers to discuss/debate differences in approach. However, they are not debugging aids.

[gnaritas]

Actually many of us do find it a bad thing. Useless comments are worse than no comments.

[MattSayar]

sed 's/\/\/.*//g' shittyComments.c

[theorique]

you can get even crazier if you add in plenty of spurious logging

# print out the value of x prior to increment print("x value prior to increment: %d" % x)

# increment the value of x x += 1

# print out the value of x after increment by one print("x value after increment by one: %d" % x)

[arethuza]

I've seen quite a lot of code that kind of looks like this:

   // Increment the total
   log.Debug("total before increment=" + total);
   total++;
   log.Debug("total after increment=" + total);
   

I find myself looking at it and going where is stuff actually happening!

I sort of wish someone would allow comments and logging to be combined as language features.

[throwaway-864]

Check out Smart::Comments module in Perl [1].

It allows the specially-formatted comments to produce debugging output.

From the synopsis:

    use Smart::Comments;
     
    my $var = suspect_value();
     
    ### $var
     
    ### got: $var
     
    ### Now computing value...
     
    # and when looping:
     
    for my $big_num (@big_nums) {  ### Factoring...      done
        factor($big_num);
    }
     
    while ($error > $tolerance) {  ### Refining--->      done
        refine_approximation()
    }
     
    for (my $i=0; $i<$MAX_INT; $i++) {   ### Working===[%]     done
        do_something_expensive_with($i);
    }

[1] https://metacpan.org/module/Smart::Comments

[einhverfr]

Noooooo..... Not magic comments.............

Magic comments are evil, the pox of the earth, etc. I have nothing good to say about comments as code. This totally messes up the separation between code and comment.

[einhverfr]

The typical case where this happens is that the logging was added because of some bug somewhere and this was put in place to figure out what was going on with total. See it as an archaeological record more than anything else ;-)

[theorique]

Hm, my code didn't format as intended. What you wrote is what I meant.

[flatline3]

I prefer code where I can skim the comments and see the major plot points, at a glance.

[dllthomas]

If you need to skim the comments to see how a function is doing what it's doing, the function is too long.

[barrkel]

Maybe the compiler needs to see the whole function in order to properly optimize register usage, because the function is on the critical path.

There is sometimes more to code than readability, unfortunately. I have worked with functions thousands of lines long that can't be broken up without losing a few percentage points of speed - but these functions are called millions of times.

[dllthomas]

It's always a matter of heuristics, for sure. When you need to modify code in a way that's less than readable/obvious, then you start dropping in comments to compensate. Your first pass should be understandable and obvious and readable, with comments typically restricted to documenting functions and interfaces.

[LiveTheDream]

Effective use of macros or inlining could solve that problem.

[barrkel]

Over 2,000 lines with macros. Inlining didn't give good enough results (at the time).

[flatline3]

When it can take 3-4 statements to perform a single logical operation, there is still value in summarizing each block with a comment, even if the function isn't "too long".

[gnaritas]

That's what function names are for. Comments don't need to summarize. A useful comments says why code is this way, it doesn't summarize or repeat code.

[flatline3]

> That's what function names are for.

A single function for every 3-4 line operation would result in incredibly disjointed code, and would require more explicit documentation of invariants because that function can now be called elsewhere (at least inside of the given translation unit).

> A useful comments says why code is this way, it doesn't summarize or repeat code.

That's nonsensical. Why wouldn't you want to abstract the complex?

[arethuza]

You would actually write an "Increment the total" comment?

[spiffytech]

Some people certainly do! My favorite examples of how not to write comments are these code snippets from the API guide I was given at a previous job. The other 60 pages of API documentation are just like this- all what and no why.

The problem isn't that these comments are harmful (they're not), but that inserting these comments made the coder feel like they'd done their job of commenting their code well, when in actuality the comments provide no insight to why certain things are called or instantiated, or what certain values represent; critical knowledge one needs to extend the code beyond the specific example cases the API guide presented.

----

  ‘ A for loop iterates through each row of DataGridView
  For Each row In DirectCast(Me.DataGridView1.Rows, IEnumerable)

----

  Dim frmTakeBackTask As New TakeBackTask
  ‘ Public oTaskData of TaskBackTask gets populated from the local object oTaskData
  frmTakeBackTask.oTaskData = oTaskData

----

  ‘ A For loop is initiated to iterate through each child node contained 
  ‘ in the XML document
  For Each record In xmlDoc.ChildNodes.ItemOf(0).ChildNodes
      ‘ A nested For loop is initiated to iterate through each column
      For Each column In record.ChildNodes

[jbl]

I probably wouldn't write "increment the total", but I think it makes sense to comment on what the total is/represents, or why the total is incremented in some particular way (if it's non-obvious).

My beef with "increment the total" comments is not that they are there, but rather that they don't help me get the big picture.

[flatline3]

That example is rather hyperbolic and not particularly useful. I can't recall the last time in 15 years that I thought "this code has too many comments!"

[gms7777]

Back in college I was a teaching assistant for CS classes and graded a lot of what was very often very poorly written and majorly undercommented code. But I do remember once getting an incredibly unnecessary 2 page long comment for a 10 line function.

That may be the only time that thought has gone through my head.

At my first internship, the code base had basically no comments in it, but was in general very clean, very organized, and there was a ton of thought put into naming and organization for readability. It was a good exercise for me working like that because it forced me to not rely on comments to explain messy code. But I also remember having long debates about what to name a variable to make it perfectly clear to the next person reading this code what it does (and often times ending up with excessively long variable names) and thinking "wow...this is a waste of time. You could just add a 1 line comment"

[dahvyd]

Consider the standard Java cough paradigm used by multitudes of developers, and on by default in many Java IDEs:

    /* Gets the person's name
       @returns the person's name */
    public String getName() {
       return name;
    }

That is insane. The comment adds nothing to anyone's day and helps no one better understand the method than after simply reading the method signature.

[flatline3]

It generates auto-docs, which are useful. It's just a ridiculously verbose way to do it, and it would be preferable if the documentation could be generated without the repetitive comment.

[arethuza]

"I can't recall the last time in 15 years that I thought "this code has too many comments!""

I've thought that every time I see a source file that contains an automatically generated header built from the revision history.

[creativename]

I feel like there are some people who go overboard on the formalities of commenting (specific format, etc.), but in general I can't think of one instance where I've thought "man, I wish I (or someone else) hadn't spent time explaining what this does".

I even find that when I write comments to explain what a specific method is intended for, it helps me avoid violating the single-responsibility principle. If I clearly spell out what I'm trying to accomplish, it helps keep me focused.

To those who say that the code should be elegant enough to be read on its own, there are some cases where the business logic involved is really what needs to be explained. At the same time, what is elegant and concise for you may appear obfuscated and confusing for someone else. You may argue that they should know all the techniques that you know, but that's just the reality of working with others sometimes.

[lawn]

> I can't think of one instance where I've thought "man, I wish I (or someone else) hadn't spent time explaining what this does".

There are good uses of comments, but there are also bad ones. From Coding Horror [1] an example:

    '*************************************************
    ' Name: CopyString
    '
    ' Purpose: This routine copies a string from the source
    ' string (source) to the target string (target).
    '
    ' Algorithm: It gets the length of "source" and then copies each
    ' character, one at a time, into "target". It uses
    ' the loop index as an array index into both "source"
    ' and "target" and increments the loop/array index
    ' after each character is copied.
    '
    ' Inputs: input The string to be copied
    '
    ' Outputs: output The string to receive the copy of "input"
    '
    ' Interface Assumptions: None
    '
    ' Modification History: None
    '
    ' Author: Dwight K. Coder
    ' Date Created: 10/1/04
    ' Phone: [phone]
    ' SSN: 111-22-3333
    ' Eye Color: Green
    ' Maiden Name: None
    ' Blood Type: AB-
    ' Mother's Maiden Name: None
    ' Favorite Car: Pontiac Aztek
    ' Personalized License Plate: "Tek-ie"
    '*************************************************

Now imagine something like this exists for every function and you're reading the source code... Annoying.

Others are less extreme of course, but repeating the code in comments is bad and even harmful if you forget to update the comment as well as the code. DRY is a good principle to have.

Of course "all comments are bad" is simply wrong, comments are essential to explain decisions or non-obvious snippets or gotchas.

[arethuza]

Reading this discussion (and posting a comment about s-expressions) got me reading about Lisp[1], and then wondering about contemporary Lisp implementations, and then to Arc where I found this amusing comment by our host:

"Object-oriented programming generates a lot of what looks like work. Back in the days of fanfold, there was a type of programmer who would only put five or ten lines of code on a page, preceded by twenty lines of elaborately formatted comments. Object-oriented programming is like crack for these people: it lets you incorporate all this scaffolding right into your source code."

http://www.paulgraham.com/noop.html

[1] I was paid to program in Common Lisp for about 6 years. However, this was a while ago so I was attempting to refresh my memory.

[slurgfest]

What is interesting about reading this discussion is that all of the 'examples' used in order to show that comments are bad are totally implausible. On the other side, the situation of 'no comments at all' is actually ubiquitous, in reality.

Writing out what you are doing takes a little work, and requires at least briefly thinking about it. It also means you can be embarrassed if your code is doing something irrational or unintended, and looking at everything again when you make major breaking changes.

By Occam's Razor, it seems more likely that complaining about comments is driven by an unwillingness to produce them more than actual practical problems created for others by their presence.

[creativename]

Yeah, that's exactly the kind of formality and over-commenting that I meant by "I feel like there are some people who go overboard on the formalities of commenting (specific format, etc.)". I saw a lot of examples of that at my old employer where they had tried (and failed) to automate some of their documentation years and years ago.

It's nice to have a brief description of what a class (or in many cases, a method) is intended for, etc. As others have said, it saves time each successive programmer from having to fully understand all of the source code.

[lawn]

Ah I see, misunderstood a bit.

[julsonl]

The issue I have with commenting is some people enforce it for the sake of having comments in place, which would most of the time describe the "what" and the "how" of the code, rather than the "why", which in my opinion, where most of the value lies. In Java, the usual offenders would be the getter and setters in POJOs, like:

  * Returns the name
  * @return the name
  */
 public String getName();

[flatline3]

Comments like that exist simply to appease documentation tools that can't derive those comments automatically.

The net gain is that you get nice API documentation. The downside is that you have a verbose and obvious comment in the source.

[slurgfest]

Aren't such comments usually autogenerated by the IDE or such tools?

[wreckimnaked]

There's some debate on this: http://queue.acm.org/detail.cfm?id=1053354

[wanderr]

The only thing worse than uncommented code, is wrongly-commented code. In my experience, code is almost always wrongly-commented, either because the programmer wrote the comment wrong in the first place, or because they wrote the code wrong, or because the code was later updated to do something different, and the comment was not updated to reflect the changes. In my experience, especially in an old codebase, it's extremely rare to find a piece of code that is both thoroughly and accurately commented.

Given that reality, I would rather forego the comments for readable code. Readable code tells me what is going on, and doesn't lie!

[einhverfr]

In my considered experience, those who are most hostile to unnecessary comments tend to put the most comments in their code. It isn't an argument against code comments, just being very picky about what is a useful comment collaboration-wise.

[ucee054]

The problem is not when programmer (A) writes the code and the comments correctly.

Nor when jackass(B) updates the code and not the comments, making them misleadingly worse than no comments at all.

But when the code now has to be maintained by programmer (C). This means you.