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

Block Comments Are a Bad Idea

futhark-lang.org

Post reply on HN
Print view View original

31–40 of 84 posts

Re: Block Comments Are a Bad Idea

#31

Post by okdana »

lozenge wrote: post #5

Surely the solution is heredocs? You effectively define your own comment closing string at the comment opening point.

I use heredocs for 'commenting out' code in shell scripts a lot. For example:

    :
In some languages there is a very slight performance impact to doing this, however. Especially in the shell, because it actually has to juggle file descriptors whenever a heredoc or herestring is involved — even if you're directing it into a built-in like `:`. (It only costs a few-dozen microseconds though.)

Also, heredocs are irritating because they usually can't deal with indentation properly. bash and zsh support the `Python's triple-quotes seem to solve all of these problems, and they're one of the best things about Python's grammar IMO. I wish every language had that, combined with the ability to treat expressions as statements. It'd be a little ugly in C-like languages, but certainly usable:

    '''
    my comment
    ''';

Re: Block Comments Are a Bad Idea

#32

Post by moomin »

dustingetz wrote: post #20

Clojure nailed this, you can throw a comment in the middle of some nested expression, e.g. when building up React.js forms: [:div [:p "hello world"] #_ [:pre "this debug block is commented out"]]

This works providing you wanted exactly one expression commented out. It's useful, but it's not perfect.

Re: Block Comments Are a Bad Idea

#35

Post by ragebol »

iiv wrote: post #2

How would one do inline comments without block comments? I don't know if Python's triple-quote can be used inline, but otherwise that seems like a good solution. I am not entirely familiar with Python comments, does any of his arguments apply to triple-quotes?

Yes, that is very well possible.

However, I do not recommend using triple-quotes for comments, as git diff only shows 2 lines with quotes while the actual difference is much bigger.

Re: Block Comments Are a Bad Idea

#36

Post by jstewartmobile »

I will second this from bitter experience.

Was translating a very old Pascal program. My editor didn't have syntax highlighting for it. Spent a couple hours translating a very large function. Wasn't until I finished that I realized it was wrapped in a very large block comment.

That, and most decent editors have a "comment current selection" feature that makes single-line comments easy enough.

Re: Block Comments Are a Bad Idea

#37

Post by umbrai_nation »

chrismorgan wrote: post #24
iiv wrote: post #2

How would one do inline comments without block comments? I don't know if Python's triple-quote can be used inline, but otherwise that seems like a good solution. I am not entirely familiar with Python comments, does any of his arguments apply to triple-quotes?

I view inline comments as a code smell in most languages; I can’t think off-hand of having seen even one occasion where the code couldn’t be tweaked into another nicer form that didn’t depend on inline comments.

I use them with functions that have too many arguments. It's not always feasible to fix the problem at the source.

damageDealt = calcDamage(weaponType, monsterType, DamageType.FIRE, null /* specialEffectFlags /, false / hasMagicTargeting */ );

It's definitely a code smell, but it's much better than nothing and I'm always glad to see these comments when I come back to the code.

Re: Block Comments Are a Bad Idea

#38

Post by Athas »

stinos wrote: post #29
fortythirteen wrote: post #18

"I don't like something, therefore it is BAD " I've never had an issue with a block comment that couldn't be fixed in a couple seconds. The usefulness and readability of a well formatted block comment, especially for documentation generation, far outweighs any inconveniences in fixing a broken implementation.

usefulness and readability of a well formatted block comment, especially for documentation generation it's indeed a bit strange the OP doesn't mention that as an advantage, accoording to the OP the first main purpose is just that it is "perceived that line comments are impractical for long comments"

Line comments are no hindrance to documentation generation. Extracting the contents from a paragraph line comment is a rather simple regular expression[0]. Haskell almost exclusively uses line comments for documentation, and it works fine. You write it like this (the '|' is to indicate that it's a doc-comment):

    -- | Compute this and that.
    -- Parameter @x@ is the good one, and
    -- parameter @y@ is the bad one.
    --
    -- The function works well and runs in time
    -- proportional to $O(n**n**n**n)$.
    f x y = ...

Re: Block Comments Are a Bad Idea

#39

Post by Athas »

oct wrote: post #13

OCaml actually has correct block comments by his definition (and no line comments). This does lead to the odd fact that you can't have an unterminated string literal in a comment, which usually isn't a problem, but can be surprising.

Does this mean that the following comment would be a syntax error in an OCaml program?

    (* Strings are enclosed by '"'. *)

Re: Block Comments Are a Bad Idea

#40

Post by [deleted] »

StavrosK wrote: post #23
StevePerkins wrote: post #22

I really appreciate class-level and method/function-level comments, in languages that have a special format for them to assist with generating documentation (e.g. Javadoc, Scaladoc, JSDoc, etc). A couple of years back, the company that I work for had a series of lunch-n-learns where each presenter did a chapter of Robert Martin's "Clean Code". One of the chapters deals with comments. Not using them as a crutch, and f…

It's kind of surprising to me that anyone past junior-level development doesn't already have it hammered into them that "code is how you did something, code is why you did it". Also, if you can't possibly be any less clever in your code, then leave a comment explaining the "how", and apologize that you couldn't make it any simpler.

[deleted]
Post reply on HN