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

71–80 of 198 posts

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

#71

Post by tveita »

icebraining wrote: post #27
koonsolo wrote: post #17

Comments say what your code does, your code says how you do it. The swap example is trivial, but for most functions it is good to add an API comment, because how you use the function shouldn't depend on how it's implemented, but what it should do, described in the comment. That way you can change your implementation as long as you don't change the contract. In other words, changing how your code does something should…

Well, this is Haskell we're talking about. Between the name, type signature and the fact that most functions are pure (so, no side-effects to describe), it's often obvious what they do.

Like

  () :: Monoid m => m -> m -> m
  (^?) :: s -> Getting (First a) s a -> Maybe a
As a Haskell beginner I didn't find it to be a particularly self-documenting language. Between the use of custom operators and point-free style you can write a lot of code without naming anything to give a hint about what you're doing.

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

#72

Post by anthracis417 »

seanmcdirmid wrote: post #63
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…

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

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

#73

Post by notduncansmith »

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…

Sometimes, comments are a justification. Sometimes you have to do things that seem like the wrong thing to when reading the code (like sending a POST request instead of a GET when a GET is clearly more appropriate, but you have to talk to a poorly-written API that will only respond to POSTs on that route). Comments help rationalize that decision for the next guy.

I also find TODO comments quite helpful. It requires far fewer brain cycles to process a TODO comment than to parse the code, figure out what it's doing, and make an assertion that it's incomplete.

Comments can also make code much more approachable to junior programmers, who may not have heard of principles like Tell Don't Ask, or Composition Over Inheritance. When I'm working with a junior dev, I find that comments usually reduce the number of interruptions I receive that are along the lines of, "Hey why did you do this thing this way?"

Really, it's just not a good idea to make sweeping generalizations like, "Comments are always failures". The real world has time and budget constraints, and comments are sometimes the most effective way to satisfy those without screwing the next developer to read the code.

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

#74

Post by jabbrwcky »

Code may explain what your code is doing, not necessarily why it is doing what it does in the way it does.

Comments may be a code smell when it is necessary to explain what your code is doing.

Anywhere where you have some freedom to solve a problem one way or the other it may clarify why the implemented approach was chosen.

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

#75

Post by ttty »

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.

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

#76

Post by nirvdrum »

seanmcdirmid wrote: post #63
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…

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

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

#77

Post by ilitirit »

There are times when you absolutely want to comment something like an "Add" or "Swap" function.

eg.

// The reason we use a custom swap function instead of

// the one that is shipped with the framework is because

// of an edge-case that occurs quite frequently in our

// scenario

// Refer to Change Request 345.

void Swap (Foo a, Foo b) ....

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

#78

Post by nirvdrum »

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.

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

#79

Post by pessimizer »

bnegreve wrote: post #14

This is not convincing to me because the examples are trivial: -- swap the elements of a pair swap :: (a,b) -> (b,a) Yes this is redundant. let b=a+1 -- add one to 'a' Yes this is also redundant Does it mean that every piece of code can be expressed as clearly as in a one-line comment in natural language? I don't think so.

I have never seen comments like these except during arguments that good code doesn't need comments.

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

#80

Post by auxbuss »

daemonk wrote: post #39

Write comments that explain why a certain line is there. Let's say you are parsing a standard tab delimited file. You find that the tab delimited file has some non-standard features, so you have to write some extra lines of code to handle it. For people who thinks the code just parses a standard tab delimited file, these lines will be confusing, so you comment these lines and say why you included them.

Or create a function to handle that case, name it appropriately, and call it. Thus, no comment is required. You can also test the additional method in isolation, if you wish.

I appreciate that this type of thing is language dependent.

Post reply on HN