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

21–30 of 84 posts

Re: Block Comments Are a Bad Idea

#21

Post by simias »

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?

You mean comments in the middle of a line of code? I don't think I've ever done that (and I write a lot of C which would allow it). Seems like a readability nightmare to me, even with proper syntax highlighting.

I guess it could be useful if you want to temporarily debug the middle of a line for debugging purposes but in this case you could just add a line break if blockquote didn't exist.

That being said I don't feel very strongly about this topic, I let emacs handle the commenting for me so I never really have issues with nested comments. Besides commenting comments is probably only useful for temporary debugging.

I do feel strongly about people committing commented/dead code however, it's just distracting and misleading. Nowadays versioning your code is just one `git init` away so nobody should be worried about keeping old dead code "just in case".

Sample code is acceptable however, I like Rust's approach where commented sample code can actually be tested to make sure it's up to date.

Re: Block Comments Are a Bad Idea

#22

Post by StevePerkins »

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 focusing on making the code readable instead.

The presenter, and one of the more influential archs in the room, was excessively dogmatic about it. Everyone ultimately left the meeting with the message that ALL comments (especially BLOCK style comments!) are "a bad code smell" per se. Overnight, everyone in the department all but stopped writing code comments.

Fast forward two years, and now it's a complete and utter nightmare to touch anyone else's code... or even your own code that you haven't seen in awhile!

Now, I understand eschewing the auto-generated blocks that your IDE might throw on the class level (e.g. "Created by John Doe, on 2017-10-11"). I understand not placing Javadocs on getters and setters and other trivial methods. I understand rejecting clutter.

However, for any non-trivial unit of code... you owe it your peers, your successors, your future self who has to maintain this later, and just the gods of professionalism in general, to throw on a brief comment blurb signalling the intent of the class or method/function.

Re: Block Comments Are a Bad Idea

#23

Post by StavrosK »

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.

Re: Block Comments Are a Bad Idea

#24

Post by chrismorgan »

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.

Re: Block Comments Are a Bad Idea

#25

Post by andruby »

narag wrote: post #14

This is one of the signs that we're doing it wrong with programming languages. We're dealing with text. A program can be expressed in text, actually every piece of information can be converted to text some way or another. The question is if it's the right way to do it. It's not. I know why we chose text at the time. It doesn't make sense today. In this case, we should be using a tool that would let us write comments…

What are you suggesting? Some kind of "rich text"? Or are you suggesting visual programming?

Re: Block Comments Are a Bad Idea

#26

Post by cat199 »

Athas wrote: post #12
lozenge wrote: post #5

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

Yes, heredocs (or "here-comments", since you want them ignored, not just stored in a string variable) would likely be a solution for all but the most pedantic. The final recourse of the pedant would be to point out that no single closing string would be appropriate in all cases, and you are in principle required to read the code you want to comment out, in order to find a closing string that is not already contained…

:.,+n|grep eofstr

Re: Block Comments Are a Bad Idea

#27

Post by tyingq »

icebraining wrote: post #6
HlessClaudesman wrote: post #3

Commenting out whole sections of code incredibly useful for debugging and rapid prototyping.

Many editors allow you to select the section and line-comment it as a whole.

Even vim has a visual block selection mode. at the top of the block, then move down (j or down arrow) to the bottom. That marks the block. Then type the I character (insert in front of cursor), type the comment character, and press . Once you press , the inserted comment character action is repeated for the whole block.

Or non-visual block select...V% with cursor on the opening {.

Re: Block Comments Are a Bad Idea

#28

Post by juki »

vortico wrote: post #7

This is my personal preference, but from experience I prefer languages that don't shun concepts because they're bad programming practice. I can understand if something is difficult to implement or prevents other features from being added, but if a feature is possible, I say add it---it might come in handy sometimes. There's a reason languages like C, C++, Ruby, and Javascript are immensely popular. It's because progr…

> LISP/Scheme, where block comments were never a thing (I think.)

Lisp does have block comments,

    #| This is a block comment |#
You can also use feature expressions to effectively comment out code

    #+(or)
    (defun foo ...)
The reader will skip over the following sexp if the feature expression isn't true (and `(or)` never is).

Re: Block Comments Are a Bad Idea

#29

Post by stinos »

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"

Re: Block Comments Are a Bad Idea

#30

Post by cat199 »

andruby wrote: post #25
narag wrote: post #14

This is one of the signs that we're doing it wrong with programming languages. We're dealing with text. A program can be expressed in text, actually every piece of information can be converted to text some way or another. The question is if it's the right way to do it. It's not. I know why we chose text at the time. It doesn't make sense today. In this case, we should be using a tool that would let us write comments…

What are you suggesting? Some kind of "rich text"? Or are you suggesting visual programming?

I think OP is suggesting something akin to the magical automated dev tools of the 1980s (OOH ITS GRAPHICAL) which never actually came to fruition.
Post reply on HN