News for hackers. Stuff that matters.
Re:I've never seen a language's style guide recommend avoidi... by rotten on Wednesday July 23, 2014 @06:52AM (#8073657)
Of course everyone thinks they always write good clean code and therefore don't need comments to elaborate on what the heck is going on.

Unfortunately, having been doing this trade for 30+ years, I've found most people write crappy code in a hurry to try to hit some deadline based on incomplete requirements and confusing business rules. A few precious comments stuck in there can help the next guy, months or years later, figure out what the heck your original intent was or why a block of code exists at all.

As I get older, I find it helps me remember what I was doing.

One of my software developer friends was fond of saying: "the worst code I ever saw was my own!"

YES if your code is clean and elegant and well named and clear you don't need to explain anything in common language.

YES you should strive for such.

However, the REALITY is your code sucks and no one is going to want to have to figure out what the heck you were doing. A few comments would really help.

The next reality is that the typical developer may be literate in a dozen or more languages and the language du jour that you coded so elegantly in has fallen out of favor and no one remembers those dusty corners you so beautifully exploited to make something work.

Comments would help even more if you learn to use some basic grammar and spelling when you create your comments. (It doesn't have to be literature, but try to make your comments as readable as you think your code is - please!) Nothing will turn another developer off to trying to decipher your code than a few comments that make you look like a moron.

Style guides that eschew comments, IMO, are counterproductive. They feed on the developer's ego and disregard reality.

Comments cost essentially nothing to add to your code and can save it from an early death and complete refactoring by the next guy who comes along.

Re:I've never seen a language's style guide recommend avoidi... by augustl on Wednesday July 23, 2014 @07:04AM (#8073689)
I wonder where the idea comes from that people that write code that's hard to understand, will write comments that are easy to understand.
Re:I've never seen a language's style guide recommend avoidi... by DanBC on Wednesday July 23, 2014 @07:38AM (#8073780)
Good programmers sometimes have to do weird things.

Leaving a note about that weird thing is probably a good idea.

Re:I've never seen a language's style guide recommend avoidi... by dllthomas on Wednesday July 23, 2014 @11:38AM (#8074928)
I agree with this, but I also think it's better if you can avoid the weird thing.
Re:I've never seen a language's style guide recommend avoidi... by notduncansmith on Wednesday July 23, 2014 @11:00PM (#8078035)
In my experience:

A novice programmer will just do the weird thing (no comments).

An intermediate programmer will spend twice as much time as they should, trying to think of an elegant solution, before doing the weird thing anyways (and maybe leaving a comment).

A good programmer will just do the weird thing, leave a comment, and move on.

Re:I've never seen a language's style guide recommend avoidi... by dllthomas on Thursday July 24, 2014 @01:57PM (#8081138)
I somewhat agree, except possibly for the "should". I think that trying to think of an elegant solution (and then accepting that you can't, where appropriate) is an important learning process. Of course this depends on context; spending time on learning is sometimes inappropriate.
Re:I've never seen a language's style guide recommend avoidi... by notduncansmith on Saturday July 26, 2014 @03:19PM (#8090490)
I agree with that. Perhaps more accurate phrasing would be "more time than the seasoned developer would have". Part of getting to the third stage is learning those types of lessons during the second stage - which only comes with experience.
Re:I've never seen a language's style guide recommend avoidi... by tbrownaw on Wednesday July 23, 2014 @11:13AM (#8074775)

    -- NOTE
    -- This is called by the database-level DDL trigger.
    -- Do not drop it. Do not break it.
We don't have a dev/qa environment, and tend to be a bit... lax about change management. There are a few pieces of code that this is particularly unsuitable for.

    function f_soundex (p_in varchar2) return varchar2
    is
    -- [name of specific source file from one of our other systems]
    -- If the first (kept) letter has the same code as the following letter,
    -- a proper Soundex ignores that following letter. The [other system] soundex
    -- keeps it.
Sometimes it is necessary to do weird things for compatibility reasons.

    // See http://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=98335
    // Apparently, DestroyHandle doesn't get called properly when a control is disposed. Since this
    // makes Invoke() hang, we have to fix it.
Sometimes external libraries/frameworks have bugs to work around.

    /* Don't let things scope to the repeat block. Even when they aren't used, they
       make the end statement slow. read-record.i has strong scoping for the data
       tables, and everything else is lifted to procedure scope. */
Sometimes there are performance reasons for doing things in a particular slightly odd manner. Sometimes there are correctness reasons (as with a 9-line comment earlier in the same program as this last example).
Re:I've never seen a language's style guide recommend avoidi... by nirvdrum on Wednesday July 23, 2014 @07:27AM (#8073746)
Well, native language and programming languages aren't the same thing and you express yourself differently in them. That's basically a given.

But comments are most useful when they explain why something is being done, not what's being done. The latter is usually simple to work out with even the most hideous code. But if I don't know what you were trying to do or why you did something in a particular way, seeing what you did alone may not be all that helpful, especially when maintaining code.

Re:I've never seen a language's style guide recommend avoidi... by couchand on Wednesday July 23, 2014 @08:32AM (#8073980)
native language and programming languages aren't the same thing and you express yourself differently in them

Indeed. However, when developing software I'd expect that the responsibility is first to express yourself clearly in code and only second to express yourself in prose, which means if you're taking very much time to do the latter it's time that could be spent doing the former.

Re:I've never seen a language's style guide recommend avoidi... by gms7777 on Wednesday July 23, 2014 @12:39PM (#8075299)
The idea is that if you do a little bit of the latter now, you will save yourself or someone else a lot of time doing the former later.
Re:I've never seen a language's style guide recommend avoidi... by brazzy on Wednesday July 23, 2014 @07:33AM (#8073763)
But all too often, people who write hideous code sprinkle it with comments that merely explain what is done, at the lowest level.
Re:I've never seen a language's style guide recommend avoidi... by nirvdrum on Wednesday July 23, 2014 @07:37AM (#8073776)
Yes. The industry is full of hacks. I don't see how that's a problem with comments though. They're going to write hideous code with or without comments.
Re:I've never seen a language's style guide recommend avoidi... by brazzy on Wednesday July 23, 2014 @07:50AM (#8073822)
The problem is that comments visually bloat the code and make it harder to understand. Bad code with useless comments is worse than bad code with no comments. And that's not even counting comments that are out of date and misleading...
Re:I've never seen a language's style guide recommend avoidi... by nirvdrum on Wednesday July 23, 2014 @08:07AM (#8073876)
And bad code with good comments is more useful than bad code with no comments. It strikes me that replacing "comments" with "tests" in much of our thread would lead to the same outcome. I guess we're just going in circles on this one.
Re:I've never seen a language's style guide recommend avoidi... by dragonwriter on Wednesday July 23, 2014 @11:52AM (#8075000)
> The problem is that comments visually bloat the code and make it harder to understand.

That's a good reason to avoid breaking up logical blocks of code with comments.

Its not a good reason not to comment.

> Bad code with useless comments is worse than bad code with no comments.

That's a good reason to have code review (which includes review of comments) to ensure that there is neither bad code nor useless (including out of date or misleading) comments.

Re:I've never seen a language's style guide recommend avoidi... by AlisdairO on Wednesday July 23, 2014 @08:28AM (#8073955)
I think because most people find written english easier to produce than clean code.

Comments have certainly aided me enormously in navigating very large, sometimes crufty, codebases.

Re:I've never seen a language's style guide recommend avoidi... by peaton on Wednesday July 23, 2014 @09:18AM (#8074176)
I don't mean this negatively, but in my experience as a high schooler and in college, the programming crowd tended to be lacking in written (communication) skills. This is certainly a huge blanket statement, but for younger programmers today I think the stereotype has at least some truth.
Re:I've never seen a language's style guide recommend avoidi... by notduncansmith on Wednesday July 23, 2014 @11:04PM (#8078042)
There are some people whose code I'd be terrified to maintain, if their code/comments are anything like their text messages.
Re:I've never seen a language's style guide recommend avoidi... by seanmcdirmid on Wednesday July 23, 2014 @07:01AM (#8073678)
> Comments cost essentially nothing to add to your code and can save it from an early death and complete refactoring by the next guy who comes along.

Whatever their benefits are, this is not true at all. Comments are expensive to write and maintain. They are VERY VERY expensive to maintain because there is no automated way to test them.

Re:I've never seen a language's style guide recommend avoidi... by reitanqild on Wednesday July 23, 2014 @08:13AM (#8073891)
Disagree.

Reason: In Software Archeology (a.k.a. maintaining legacy code) you are often happy to get any kind of clue as to what went on inside someones head. Maybe they saw an edge case?

Of course you should write self-documenting code with variables and function names that explains most of it but when you either have to

1. factor out a new function

do_this_to_fix_that_weird_thing(weird state)

or

2. have to add a line

state == weird ? fix = fix+1:continue // weird is a weird state that sometimes occurs even though vendors api docs says otherwise.

please think twice.

Outdated comments are a problem but very often a problem I'll happily deal with compared to not having them at all. If a comment doesn't make sense you can also try checking VC history.

Re:I've never seen a language's style guide recommend avoidi... by otikik on Wednesday July 23, 2014 @10:29AM (#8074531)
I will take 3

3. fix_bug_that_occurs_even_when_api_docs_say_otherwise(weird)

Re:I've never seen a language's style guide recommend avoidi... by nirvdrum on Wednesday July 23, 2014 @07:23AM (#8073735)
I've certainly come across situations where the code and the comment don't line up, but that seems to arise from laziness more than anything else. If the comment is directly attached to a region of code, most developers I've come across will process both at the same time. The area where I see it fall apart most commonly is with javadoc-style comments. Most IDEs will even flag these issues, but they're often ignored.

A comment on its own isn't inherently harder to maintain any other piece of code or documentation. Sure, it's not zero cost, but I find more often than not they exceed the cost associated with not commenting.

Re:I've never seen a language's style guide recommend avoidi... by remon on Wednesday July 23, 2014 @08:46AM (#8074037)
You're not wrong but you're isolating the cost of commenting a certain piece of code. It's really about the net time investment. If you create comments the idea is that code maintenance in the future is easier and/or introduces less risk of introducing new bugs (and you'll agree those are even more expensive to resolve). That said it remains a bit of a subjective discussion.
Re:I've never seen a language's style guide recommend avoidi... by anthracis417 on Wednesday July 23, 2014 @07:17AM (#8073720)
Forgive my ignorance, but why and how would you test a comment? They don't do anything, there is no instruction for the machine to understand or run.
Re:I've never seen a language's style guide recommend avoidi... by knowaveragejoe on Wednesday July 23, 2014 @07:36AM (#8073770)
He's referring to the problem of comments becoming out of sync with the code they're referring to. Not everyone updates comments as they update code.
Re:I've never seen a language's style guide recommend avoidi... by jdbernard on Wednesday July 23, 2014 @12:33PM (#8075255)
And those people deserve a special place of torment all their own. How hard is it really to update, or at least delete comments that are no longer relevant when you modify the code?
Re:I've never seen a language's style guide recommend avoidi... by knowaveragejoe on Thursday July 31, 2014 @06:14PM (#8117328)
It's not that it's hard, it just may not be apparent that you need to do so.
Re:I've never seen a language's style guide recommend avoidi... by seanmcdirmid on Wednesday July 23, 2014 @07:54AM (#8073845)
The comments are meant to be read and used to understand code. So you must test them like any other artifact to ensure that they are a net positive and not a net negative. Programmers make mistakes, which hopefully fail a test or at least cause a crash. Because comments can't be executed, neither of those will happen; they have to be verified manually
Re:I've never seen a language's style guide recommend avoidi... by AlisdairO on Wednesday July 23, 2014 @08:18AM (#8073902)
Isn't that fairly easy to do during a code review?
Re:I've never seen a language's style guide recommend avoidi... by dllthomas on Wednesday July 23, 2014 @11:41AM (#8074950)
Only when all comments only refer to local information. There is nothing to check that the comment in that other file that refers to this code was correctly updated.

Some system of backrefs could handle this, of course, but I'm not aware of anything in use...

Re:I've never seen a language's style guide recommend avoidi... by dragonwriter on Wednesday July 23, 2014 @12:14PM (#8075130)
> Only when all comments only refer to local information. There is nothing to check that the comment in that other file that refers to this code was correctly updated.

The only time a comment should refer to non-local information is to document an assumption or basis of the local code, which is still correct information about the local code as long as it is the assumption/basis of the local code, even if the assumption is (or later becomes) false.

Of course, it would be useful to have a way to verify the information about the assumptions to see if they have become false, but that's not about validating the comment, that's about validating the code it comments, since if the assumption is false, it is quite likely that the code needs to change (and this may not be something that unit testing the local code can discover, as such comments often are not about correctness but about choosing a less-than-obvious alternative correct approach for optimization, or to work around a quirk of the code being called, etc.)

Re:I've never seen a language's style guide recommend avoidi... by dllthomas on Thursday July 24, 2014 @01:54PM (#8081118)
I'm not sure I disagree. In practice, though, I certainly encounter comments communicating nonlocal information ("This is used in ..."), and of course these are the least likely to remain accurate. "All comments is local" is something we should start drumming into people - I don't think anyone ever said this to me explicitly.
Re:I've never seen a language's style guide recommend avoidi... by seanmcdirmid on Wednesday July 23, 2014 @08:28AM (#8073952)
Sure, code review is a very manual approach.
Re:I've never seen a language's style guide recommend avoidi... by AlisdairO on Wednesday July 23, 2014 @08:53AM (#8074064)
Yes, what I mean is, if you're doing code review then there's virtually no additional cost - you're looking over the changes anyway. It doesn't matter that the process is manual if you're already doing it. If you're not doing code review, then you perhaps either have some organisational issues or you have coworkers who are sufficiently responsible that you can trust them to do basic code hygiene work like keeping comments up to date.
Re:I've never seen a language's style guide recommend avoidi... by seanmcdirmid on Wednesday July 23, 2014 @09:41AM (#8074283)
I think comments would be more difficult to review than code, since you'd have to carefully make sure they are meaningful by examining the code, without the context of the programmers involved. Alternatively, you could add comments during code review to document the review and basically redo the comments on each review...maybe.

Comments also break flow and get in the way of code reading, but could probably just be hidden during review.

Re:I've never seen a language's style guide recommend avoidi... by dragonwriter on Wednesday July 23, 2014 @11:55AM (#8075016)
> I think comments would be more difficult to review than code, since you'd have to carefully make sure they are meaningful by examining the code, without the context of the programmers involved.

Actually, that only makes them hard to review if you are trying too hard, which defeats the purpose of reviewing comments -- if it is hard to validate the utility of a comment without the context of the programmer involved, its a bad comment and needs, at a minimum, to be clarified.

After all, the whole point of a comment is to communicate information to a future person who lacks the context of the programmer involved.

Re:I've never seen a language's style guide recommend avoidi... by mmhammer on Thursday July 24, 2014 @10:33AM (#8079755)
It's manual whether with a tool or without. We like using a tool because it automates the process. We find teams are more thorough in their reviews with a tool. We're also distributed, so it helps with collaboration too.
Re:I've never seen a language's style guide recommend avoidi... by peaton on Wednesday July 23, 2014 @09:17AM (#8074169)
Brings up an interesting point about perhaps using natural language processing to determine correctness of a comment. That would be prettty cool.
Re:I've never seen a language's style guide recommend avoidi... by kedean on Wednesday July 23, 2014 @09:41AM (#8074281)
If you could use NLP to verify the comment, then what would the point of the comment be? Comments are for those aspects of a program that are invisible to the compiler and IDE, the intent.
Re:I've never seen a language's style guide recommend avoidi... by peaton on Wednesday July 23, 2014 @09:47AM (#8074309)
Maybe my view of NLP is more sci-fi than reality, but I think you're missing what I meant. If you can use NLP to prove that your comment - ie the intent - which IS invisible to the compiler and IDE, then that might be cool. Practical, probably not. But I'd still be very impressed at the implications if this was possible within some error margin.
Re:I've never seen a language's style guide recommend avoidi... by ttty on Wednesday July 23, 2014 @07:21AM (#8073730)
Then you will read the comment that says to do one thing but the program will do a completely other thing. I don't see any problem, do you?
Re:I've never seen a language's style guide recommend avoidi... by mike_hearn on Wednesday July 23, 2014 @07:39AM (#8073784)
That's why good comments are about explaining WHY you're doing something, or HOW to use the code, and possibly making the code itself clearer but only if there's no way to do that by introducing better variable and method naming.

Comments are highly valuable but like any tool they can be abused, or done in such a way that they don't make things better.

Re:I've never seen a language's style guide recommend avoidi... by wtetzner on Wednesday July 23, 2014 @08:01AM (#8073862)
The point is that comments can become out of date, and there's no automated way to enforce they stay up to date.
Re:I've never seen a language's style guide recommend avoidi... by wtetzner on Wednesday July 23, 2014 @08:08AM (#8073878)
> Style guides that eschew comments, IMO, are counterproductive. They feed on the developer's ego and disregard reality.

To be fair, the style guide that's linked to doesn't actually say not to write comments. It says that if you're going to write a comment, think twice. Maybe you can make the code clearer instead.

Re:I've never seen a language's style guide recommend avoidi... by nirvdrum on Wednesday July 23, 2014 @07:33AM (#8073762)
More than the language du jour, many of us evolve. The way I wrote in code in language X today is a bit different than how I wrote it 6 months ago. This is especially true when first starting a language. Then, as I've worked in more languages, I've been exposed to better techniques and those influence how I think about problems.

At any given time I'm writing code as clearly as I can given my experience and body of knowledge. It also is representative of my exposure to and familiarity with the problem domain at that point in time. As these things evolve, my older code ceases to be as clear as I thought. It may very well not be the way I'd solve the problem again.

And that's before I need to start making changes to code clarity to satisfy a hard requirement (reduce memory usage, cache values, tighten up performance, etc.).

Re:I've never seen a language's style guide recommend avoidi... by marvin on Wednesday July 23, 2014 @07:12AM (#8073709)
Agree perfectly. "Your code should be self-documenting" is one of the memes that give you an excuse for being lazy. While true in the ideal case, very few programmers are able to (or even in a domain where it is possible to) write code that documents itself.
Re:I've never seen a language's style guide recommend avoidi... by couchand on Wednesday July 23, 2014 @08:35AM (#8073991)
It's not at all an excuse to be lazy. If your code isn't self-documenting, you need to document it. But rather than spending your time doing that, how about you improve the code instead?

Are you looking for an excuse to be lazy? How about "I'll just put a comment in there and not worry about it"...

Re:I've never seen a language's style guide recommend avoidi... by nahname on Wednesday July 23, 2014 @08:25AM (#8073937)
How can you write clean, simple comments if you cannot write clean, simple code.
Re:I've never seen a language's style guide recommend avoidi... by remon on Wednesday July 23, 2014 @08:42AM (#8074017)
It's not always a matter of being able to write clean, simple code. In fact in my experience ability is hardly ever a factor. You may not have enough time, you may have to use complex counter-intuitive APIs, the business requirements might be unclear, the algorithm might have complex components that are hard to convert to easy to read code, etc. There are literally dozens of reasons why code might not be "clean and simple" and not of all of those reasons are associated with developer know-how. Whenever this discussion comes up it tends to be a "theory vs real world" sort of discussion.
Re:I've never seen a language's style guide recommend avoidi... by commandar on Wednesday July 23, 2014 @09:23AM (#8074206)
I'm in a field (healthcare integration) where vendors constantly break spec or handle things in a quirky manner.

The actual code I work with is fairly straightforward and easy to understand functionally. I can understand the what of pretty much any of the code my organization runs in short order.

But the why is vital. This week I've implemented things for reasons I won't remember in six months. Simple, easy to understand code. I've also been fighting with another system that predates me. I can see that it's modifying the original message to map particular values elsewhere downstream, but I have absolutely no idea why or which downstream system is expecting them. I've lost hours trying to track this down when a line or two explaining WTF the piece of code exists would have told me exactly where I needed to look.

Yes, your code should be understandable and self documenting to some degree anyway. But your code doesn't exist in a vacuum, and can't document what exists external to it.

Re:I've never seen a language's style guide recommend avoidi... by remon on Friday July 25, 2014 @07:08AM (#8084596)
My sentiments exactly.
Re:I've never seen a language's style guide recommend avoidi... by levosmetalo on Wednesday July 23, 2014 @08:55AM (#8074069)
TFA is not arguing against writing comments, it's arguing againts writing obvious and meaningless comments. I'd much prefer no have no comment to 'getA' method than full blown comment saying 'ruturns B', just because before refactoring method was called getB, and the comment was meaningless then, and wrong now.
Re:I've never seen a language's style guide recommend avoidi... by pdabbadabba on Wednesday July 23, 2014 @09:07AM (#8074124)
I think rotten's response to this is that it's easy to think that your code is clearer than it really is. I think we can probably all agree with what you've said about your example, but in the real world, the decision may not always be so obvious -- either because it is genuinely a harder question, or because of an oversight. This being the case, maybe it's better to get in the habit of writing even stupid comments (within reason) as well as (of course) eliminating unexpected behavior when possible. This is merely a concession to reality: your code will rarely be perfect, and you will not always have the time/resources/inclination to polish everything the way you might like. But at least if you write a comment, future readers of your code won't be at a disadvantage in fixing your mistakes.
Re:I've never seen a language's style guide recommend avoidi... by mathattack on Wednesday July 23, 2014 @09:16AM (#8074166)
In this sense, the article doesn't add much value. If you're just saying, "Avoid unnecessary comments" you're in the same state of truisms as "Write quality code" or "Try your best".
Re:I've never seen a language's style guide recommend avoidi... by orclev on Wednesday July 23, 2014 @11:47AM (#8074972)
To be fair the article doesn't just say "avoid unnecessary comments" it actually gives some pretty concrete examples of less than ideal comments and ways in which you can make the need for a comment in that situation unnecessary. The TL:DR; of the article is essentially compile time errors are better than comments for preventing bugs so use the Type system if you can to encode your invariants rather than simply trying to document them in your code. That said, you can't always do that for various reasons so in that case it's perfectly reasonable to put comments in documenting that, but in that case at least try to capture the intent behind the code, not simply rehash the mechanics of how the code is accomplishing that. E.G. "returns a count of how many users have been flagged in the Foo system", instead of "returns user_foo_count".
Re:I've never seen a language's style guide recommend avoidi... by jgimenez on Wednesday July 23, 2014 @07:01AM (#8073679)
Hahah, I so much agree!

I also think you should target for 0 comments in an ideal world. Every time I write a comment I remind myself, can't you really write this in a more obvious way?

But reality is that exercise requires time that you don't always have

Re:I've never seen a language's style guide recommend avoidi... by otikik on Wednesday July 23, 2014 @09:37AM (#8074266)
Well that is ... sad. I have not been around for 30+ years and I see good code on a weekly basis. Maybe you should consider changing something in your environment. I assure you it is possible.
Re:I've never seen a language's style guide recommend avoidi... by kelvin0 on Wednesday July 23, 2014 @09:44AM (#8074298)
Maybe he 'sees' bad code that you would consider 'good' code. This can be a bit subjective, and also he has much more experience than you ...
Re:I've never seen a language's style guide recommend avoidi... by otikik on Wednesday July 23, 2014 @10:26AM (#8074515)
Maybe. It's still sad.
Re:I've never seen a language's style guide recommend avoidi... by Confusion on Wednesday July 23, 2014 @08:21AM (#8073919)

  A few precious comments stuck in there can help the next 
  guy [..]
More than spending that time on improving the code?
Re:I've never seen a language's style guide recommend avoidi... by peaton on Wednesday July 23, 2014 @09:20AM (#8074188)
Do you really think the time spend writing a comment is comparable to improving the code? Personally, I can't think of an occasion where that would have been true.