Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

haskell.org

Post reply on HN
Print view View original

121–130 of 198 posts

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

#121

Post by kasey_junk »

I've found there are several topics that even qualified, experienced, reasonable developers will always disagree on. dynamic vs static typing, YNGNI vs future proofing, IDE vs no IDE etc. Usually, a given developers opinion on these topics is informed by their specific experience and what has bitten them in the past.

Code comments definitely fall into this category. I've worked with developers who I greatly respect who are obsessive about code comments. I've even been told that the comments are more important than the code and in that specific context it made sense.

But my own experience and biases make me think code comments are a problem. I like to refer to them as future lies. There is virtually no back pressure on comments to keep them in sync with the code. There is no automated way to verify them and refactoring tools on comments are rudimentary at best. To put it simply, I no longer trust comments and will usually ignore them in order to verify the code itself. I can't count the number of times I've found comments that directly contradicted the code it was commenting. It isn't even uncommon to find comments that are incorrect when they are written!

As to the folks recommending comments that document the "why" of a piece of code, I'd counter that if you have a "why" you have a specification. If you have a specification it should be verified in a systematic way. So performance improvements, or specific client requirements should be encoded in tests so that they don't regress. Comments do not provide that safety.

That's not to say I never comment my code. Just that it always feels like a failure when I do. It is usually because it is cheaper to comment than to provide cleaner code or better verified specifications.

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

#122

Post by seanmcdirmid »

AlisdairO wrote: post #111
seanmcdirmid wrote: post #98

Earlier quoted context omitted.

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

Isn't that fairly easy to do during a code review?

Sure, code review is a very manual approach.

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

#123

Post by SchizoDuckie »

ARussell wrote: post #117
SchizoDuckie wrote: post #91

The thing with comments is: You should add them for people that don't want to read your code line by line. I don't want to run my internal compiler in my head when i'm reading your code, so you better make sure there's at least a docblock above every function that describes in 2 sentences what it does so I can get a global overview of what the heck this file is doing. People that suggest that 'the code is the documen…

That is exactly why once should take the time to give meaningful names to their functions, classes, and methods. If you are having a difficult time doing it, your piece of code is probably doing too much. Split it into pieces that are more easy to name.

I already assume you are using meaningful names for functions, classes and methods, as any self-respecting programmer will do.

I can completely live with a 50 line function that does magic in a legacy project, as long as I don't have to read through it.

'split it into pieces' is everybody's favorite argument, but nobody is going to pay you to refactor it. DOCUMENT IT.

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

#124

Post by AlisdairO »

augustl wrote: post #66
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…

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.

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

#125

Post by bkeroack »

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);…

Funny (and perhaps intentional) that your example comment and code disagree ("$intensity=5").

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

#126

Post by couchand »

nirvdrum wrote: post #78
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.

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…

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

#127

Post by couchand »

marvin wrote: post #70
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…

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.

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

#128

Post by gaelow »

I currently write docblocks for everything I code.

It's crazy how much time I spend on them and sometimes they are confusing because the specs change and I keep forgetting to add/remove/update something in a docblock when I rewrite some part of the code it documents (I'd say between 10-20% of my commits are docblock updates).

I believe brief or even no documentation may be the best approach until you are on the verge of releasing a stable version.

While you are on developing and testing mode, it seems a better idea to forget about comments and focus on modularity.

After all, Why would I need comments if all the rest of my team sees is an interface satisfying a previously established and well defined contract? That's why docblocks should be only documenting public interfaces, some kind of dump taken from the part(s) of the contract they implement.

I'd consider instead other top priorites on those phases:

- Keeping an homogeneous codebase in regard of design and coding guidelines and conventions.

- Re-factoring before it becomes a problem

- Writing neat unit and integration tests

And, the most important:

- Keeping a channel open with the client, constantly feeding guided demos and prototypes showing your progress to make sure you are on the right track and you didn't get it backwards, updating specs and being realistic about what can be done and what not in which time frames with the provided resources.

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

#129

Post by Huppie »

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 like how you made the comment say 'defaults to 4' while the code says 5, this pretty much sums up my experience with 'documentation comments' as well.

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

#130

Post by couchand »

augustl wrote: post #67
blowski wrote: post #29

Avoiding comments that do what your code should be doing is common practice, and I think that's what this style guide is recommending. Comments are useful to describe __why__ you're doing something, often when you are not able to change the unexpected behaviour. Whenever I build an API library, my code is littered with comments like "Acme Corp API requires this happens before that" with a link to that bit of the API…

Completely agree :) In some cases I prefer to wrap it in an aptly named function, but in other cases I prefer the whole algorithm to be in a single function, making comments a very useful tool for "naming".

in other cases I prefer the whole algorithm to be in a single function

A modern compiler can inline most of your function calls if you like. That way you can factor the code appropriately for both concerns.

Post reply on HN