61–70 of 84 posts
"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"
/**
* This is documentation.
*
* It spans multiple paragraphs.
*/
pub fn foo() {}
/**
This is documentation.
It spans multiple paragraphs.
*/
pub fn foo() {}
/// This is documentation.
///
/// It spans multiple paragraphs.
pub fn foo() {}
#[doc = "This is documentation."]
#[doc = ""]
#[doc = "It spans multiple paragraphs."]
pub fn foo() {}
Earlier quoted context omitted.
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. -- -- Th…
Rust had an RFC at one point that considered removing (some) block comments, which generated a good argument in their favour (see also the longer comment 5 replies later): https://github.com/rust-lang/rfcs/pull/1373#issuecomment-205... Essentially it's very annoying (slash slash) for blind programmers (slash slash) if their screen readers (slash slash) keep reading out (slash slash) line comment delimiters (slash sla…
This feels more like a deficiency in the screen reader than one in line comments.
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…
One can call it BAD too, but I’ve done this several times: if (self-describing) { } else if (self-describing) { } else /* description */ { } and void myfunc(int a, char *b /* optional */, ...) { Block comments are not only block, but also inline. You cannot end line comment on the same line. (Though it is easy to work around). As of good/bad: if you don’t like it personally, then don’t use it. If in group, then put t…
Put the comments at the end of the line, introducing line breaks if necessary: if (…) { } else if (…) { } else { // description } and void myfunc(int a, char *b, // optional ...) I don’t program in C or C++, but when working with the Windows API I appreciate Microsoft’s source-code annotation language which leads to being able to indicate input and output parameters, and optional ones, so that you’d wind up with some…
"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.
The author makes almost exactly your point regarding the (non)importance of these issues in practice.
What would the author have to write in order to be able to discuss the consequences of this language design choice, and be spared the barb of your wit.
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.
The D Programming language has a neat trick to block commenting out code for debugging purposes. Wrapping code in a version(none) {} block will exclude the block from compilation. The code inside the block must still be syntactically valid so it avoids the problem mentioned in the linked post. The D Programming Language - Conditional Compilation: https://dlang.org/spec/version.html
In what ways is that better than "if(false) { }"?
CSS only has block comments, and they’re eager-closing rather than nested. This makes it approximately impossible to comment out code if you add any explanations for why things are how they are or have any other comments inline, which makes me sad.
Edit: oh, wait, html comments also suck.