I've never seen a language's style guide recommend avoiding comments before • Hacker News Board

Re: I've never seen a language's style guide recommend avoiding comments before

#141

Post by jasonlotito » Wed, Jul 23, 2014, 1:03 PM UTC

AlisdairO wrote: post #119

denizozger wrote: post #55

Robert C. Martin's Clean Code book has a great section on comments: - The proper use of comments is to compensate for our failure to express ourself in code. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. So when you find yourself in a position where you need to write a comment, think it through a…

> Programmers can’t realistically maintain them. Why not? The effort involved is not very high. If you mean that they won't maintain them, well, I agree. Sometimes I fail to do so myself - but that's my laziness, not because keeping a comment up to date is actually difficult. The fact that programmers can be lazy is why we put processes in place to catch ourselves - code reviews, code style enforcement, and so on.

> Why not? The effort involved is not very high.

Because, realistically developers will be lazy. For example:

"Sometimes I fail to do so myself - but that's my laziness"

> code reviews

So, here is the thing, "programmers can be lazy." Programmers can also miss things. Code reviews don't catch everything.

So, when someone says "programmers can’t realistically maintain them", they are being realistic. Really. It's great to be hopeful, but the simple fact is, you can't trust that comments are maintained.

Re: I've never seen a language's style guide recommend avoiding comments before

#142

Post by pdabbadabba » Wed, Jul 23, 2014, 1:07 PM UTC

levosmetalo wrote: post #138

rotten wrote: post #61

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 lat…

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.

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 avoiding comments before

#143

Post by AlisdairO » Wed, Jul 23, 2014, 1:10 PM UTC

jasonlotito wrote: post #141

AlisdairO wrote: post #119

Earlier quoted context omitted.

> Programmers can’t realistically maintain them. Why not? The effort involved is not very high. If you mean that they won't maintain them, well, I agree. Sometimes I fail to do so myself - but that's my laziness, not because keeping a comment up to date is actually difficult. The fact that programmers can be lazy is why we put processes in place to catch ourselves - code reviews, code style enforcement, and so on.

> Why not? The effort involved is not very high. Because, realistically developers will be lazy. For example: "Sometimes I fail to do so myself - but that's my laziness" > code reviews So, here is the thing, "programmers can be lazy." Programmers can also miss things. Code reviews don't catch everything. So, when someone says "programmers can’t realistically maintain them", they are being realistic. Really. It's grea…

Couldn't you use the exact same argument to say that it's realistically impossible to maintain a high quality, readable codebase, so why bother trying?

There's nothing that intensely difficult about implementing processes that keep at least the vast majority of comments up to date. If you don't feel like it, or your organisation doesn't have the will to enforce it, then fair enough. That's not the same as it being impossible.

Re: I've never seen a language's style guide recommend avoiding comments before

#144

Post by mathattack » Wed, Jul 23, 2014, 1:16 PM UTC

levosmetalo wrote: post #138

rotten wrote: post #61

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 lat…

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.

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 avoiding comments before

#145

Post by peaton » Wed, Jul 23, 2014, 1:17 PM UTC

anthracis417 wrote: post #72

seanmcdirmid wrote: post #63

Earlier quoted context omitted.

> 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.

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.

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 avoiding comments before

#146

Post by peaton » Wed, Jul 23, 2014, 1:18 PM UTC

AlisdairO wrote: post #124

augustl wrote: post #66

Earlier quoted context omitted.

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.

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.

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 avoiding comments before

#147

Post by peaton » Wed, Jul 23, 2014, 1:20 PM UTC

Confusion wrote: post #116

rotten wrote: post #61

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 lat…

A few precious comments stuck in there can help the next guy [..] More than spending that time on improving the code?

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.

Re: I've never seen a language's style guide recommend avoiding comments before

#148

Post by commandar » Wed, Jul 23, 2014, 1:23 PM UTC

remon wrote: post #131

nahname wrote: post #120

Earlier quoted context omitted.

How can you write clean, simple comments if you cannot write clean, simple code.

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 s…

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 avoiding comments before

#149

Post by w0utert » Wed, Jul 23, 2014, 1:28 PM UTC

SchizoDuckie wrote: post #118

shabbyrobe wrote: post #97

I see rubbish like this in PHP (and Java) code all the time: /** * Frobnicates a foobar * * @param Foobar $foobar The foobar to be frobnicated * @param int $intensity The intensity with which the foobar will * be frobnicated (defaults to 4) * @return mixed The result of frobnicating a foobar */ function foobar_frobnicate(Foobar $foobar, $intensity=5) { // frobnicates the foobar return $foobar->frobnicate($intensity);…

I think we can all agree that this is the most blatant example of useless documentation.

It's a bit contrived but it's not even as useless as it would appear to be (if you forget about the likely intentional mismatch between the default value and its documented value).

The purpose of this comment is obviously not to clarify the code for someone working on it, but to ensure the automatically generated API docs stay consistent. I write comments like these above functions all the time, because we have a zero-warning policy for doxygen comments over here, to prevent people forgetting to document public API methods (or slacking off out of laziness). Sure, the comment block is redundant since it contains nothing that cannot be derived from the parameter names and the name of the function, but it does make sure a doxygen run will not spew warnings and errors all over the place, drowning out uncommented methods with far less obvious functionality or parameters. The redundancy is a small price to pay to enforce a good self-documented API.

I really don't understand any of the discussions about not documenting code because it should be 'clean and obvious'. First of all that's mixing up 'how' and 'why' code is like it is, second it's a small effort to write and maintain code comments (contrary to what some people like to suggest otherwise), third it can help you organize your thoughts while you are writing the code (write the steps of your algorithm in comments, then translate them to code), etc.

Personally I also like how the syntax highlighting breaks up blocks of code with API doc comments, which makes it much easier to see where functions start and end when scrolling fast, or how they can separate distinct steps of an algorithm. 'No comments' really is the inverse of 'literate programming', like most of the time, the truth is probably somewhere in the middle.

Re: I've never seen a language's style guide recommend avoiding comments before

#150

Post by otikik » Wed, Jul 23, 2014, 1:32 PM UTC

seanmcdirmid wrote: post #59

krzrak wrote: post #51

Earlier quoted context omitted.

There is no such complex function that can't be decomposed to bunch of simple(r) functions.

Often only with a deep understanding of the complex problem to understand its simplicity. But you have to ship in 4 weeks, so why not just get something working first?

> But you have to ship in 4 weeks, so why not just get something working first?

If you do that, after the deadline is over, you will get assigned another task with another 4-week deadline. And then another. The code will get increasingly complex until you can't keep with it any more. And then you will leave the company, or they will fire you. And the people who gave you that deadline will refer to you as "the guy who left that horrible mess of code".

I decided long ago that that's not how I want to live my life.

If someone gives me an unreasonable deadline, I negotiate it. Hard. By explaining the problems, and making sure everyone understands the tradeoffs being made.

And if the deadline is really immovable, I negotiate a period to refactor after the deadline is passed, and in which I am not assigned other tasks.

And if that is not possible, then I start looking for another job. Fortunately now it's a great time to be a programmer.

But hey, if that works for you, then great. To each his own.