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

131–140 of 198 posts

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

#131

Post by remon »

nahname wrote: post #120
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…

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

#132

Post by _delirium »

chiachun wrote: post #49

Similar thoughts were seen in the SICP book. "In this book we don't use many comments; we try to make our programs self-documenting by using descriptive names." http://mitpress.mit.edu/sicp/full-text/book/book-Z-H-15.html...

From the era when two poles were Lisp and C, I can sort of see that. In part because of the preference for longer identifier names in Lisp, versus cryptic abbreviations in C, some kinds of comments prevalent in C aren't as necessarily in Lisp. Instead of atoi() you'd have something like convert-ascii-to-integer.

In modern Lisp, though, it's still considered good form to include both a docstring, and internal comments explaining anything particularly tricky.

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

#133

Post by kasey_junk »

sheepmullet wrote: post #69
nodesocket wrote: post #35

I've seen this many times: ...thus they (comments) tend to diverge from actual implementation. It happens, you update/refactor code, and forget to update the comments. Thus the comments are outdated or worse not applicable anymore. Common mistake by less-detailed oriented developers. Begs the question, in this case is is better to have confusing/incorrect comments, or no comments at all?

" ...thus they (comments) tend to diverge from actual implementation." In my experience comments are no more likely to diverge than tests are. With tests you have the advantage that they must compile. With comments you have the advantage that they are inline/interspersed with your code and so get read every time the code is read. "It happens, you update/refactor code, and forget to update the comments." So then the n…

"With comments you have the advantage that they are inline/interspersed with your code"

Just as a heads up, there are lots of testing paradigms that have the tests inline with the code it is testing. That they aren't the default in most languages is most disappointing.

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

#134

Post by [deleted] »

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.

[deleted]

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

#135

Post by remon »

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.

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

#136

Post by notduncansmith »

ricardolopes wrote: post #84
ilitirit wrote: post #77

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

I think you are missing the point there. Sure, I completely agree with you that those comments are crucial, but they are not informing about the code doing a swap, they are explaining the need of the applied workaround.

That's precisely the point. In most cases, what your code is doing should be obvious; the why, as others have stated, would be otherwise completely out-of-band information, which explains the necessity for comments.

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

#137

Post by AlisdairO »

seanmcdirmid wrote: post #122
AlisdairO wrote: post #111

Earlier quoted context omitted.

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

Sure, code review is a very manual approach.

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

#138

Post by levosmetalo »

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.

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

#139

Post by krzrak »

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?

Of course, this sometimes happens, but it shouldn't be encouraged. This way you are creating technical debt, which will be very expensive to pay off.

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

#140

Post by josephlord »

couchand wrote: post #130
augustl wrote: post #67

Earlier quoted context omitted.

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.

Putting the whole algorithm in a single function isn't for the compiler's benefit but for the reader's. Especially in languages with side effects any function call you need to analyse takes time and then you need to come back to the main function and remember your mental state.

Please note that in many cases putting an algorithm in a single function is the wrong choice but there is also a cost in splitting it.

Post reply on HN