4 ms·

"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 reada

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

stinos 9y ago
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"
- Athas 9y ago
  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 = ...
  - stinos 9y ago
    Actually my point was mainly about the readability aspect, should have made that more clear: for me there usually still is a (slight) advantage in readability if every line is not prefixed. E.g. the code you show here looks rather cluttered to me. It doesn't mean it does to you of course, if you are used to it your brain just ignores those dashes. But mine doesn't, since I am not used to it. Though it would probably take me only a couple of days.
- chrismorgan 9y ago
  Rust supports block comments and line comments; the recommended style is “don’t use block comments”. I have never felt any inclination to use block comments in Rust. These examples of doc comments (using slash-star-star or triple slash instead of slash-star or double slash which are plain comments) are all equivalent, and I know which one I find to be nicest (the third, with line 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() {} (You can mix-and-match, too; I’ve combined doc attributes with cfg_attr before, to add doc comments if a certain feature is enabled, see the bonus section in https://chrismorgan.info/blog/rust-cfg_attr.html. https://chrismorgan.info/blog/rust-cfg_attr.html.)
lamacase 9y ago
"I don't have these problems, therefore they are not real problems" 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.
- fortythirteen 9y ago
  > "I don't have these problems, therefore they are not real problems" What a major mischaracterization. It was the author that implied things were objectively bad. I stated that the subject is subjective, in that there are use cases where block comments are good.
  - lamacase 9y ago
    What the author stated was: > I will argue that block comments are unnecessary, and in fact near-impossible to design and implement correctly (for my own pedantic notion of correctness) You might argue, subjectively or objectively, about the utility of the "notion of correctness" used here, but the author warns at the outset that this is the basis for the rest of the analysis. I ask again, what preface would the author need to write to satisfy your criticism? I think that it's worthwhile for the author to point out that you cannot create a block comment scheme without having some un-intuitive edge cases, and I'm curious what gave you the impression that the author was claiming an unwarranted degree of objectivity.
    - fortythirteen 9y ago
      He argued that future programming languages should get rid of them completely.
      - Athas 9y ago
        Yes, but based on an subjective judgment. I am the author of the blog post, and I tried to do my utmost to emphasize that my judgment here is highly subjective, using phrases such as "for my own pedantic notion of correctness", and "I cannot in good faith claim that [problems with block comments] occur all that often in practice". I try to make it clear that I'm not surprised, offended, or annoyed that most languages support block comments. How do you think I should have put my words, to make it clear that my opinion here is not intended as objective fact, but merely a subjective take on a language design question?

stinos 9y ago

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"

Athas 9y ago
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 = ...
- stinos 9y ago
  Actually my point was mainly about the readability aspect, should have made that more clear: for me there usually still is a (slight) advantage in readability if every line is not prefixed. E.g. the code you show here looks rather cluttered to me. It doesn't mean it does to you of course, if you are used to it your brain just ignores those dashes. But mine doesn't, since I am not used to it. Though it would probably take me only a couple of days.
chrismorgan 9y ago
Rust supports block comments and line comments; the recommended style is “don’t use block comments”. I have never felt any inclination to use block comments in Rust. These examples of doc comments (using slash-star-star or triple slash instead of slash-star or double slash which are plain comments) are all equivalent, and I know which one I find to be nicest (the third, with line 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() {} (You can mix-and-match, too; I’ve combined doc attributes with cfg_attr before, to add doc comments if a certain feature is enabled, see the bonus section in https://chrismorgan.info/blog/rust-cfg_attr.html. https://chrismorgan.info/blog/rust-cfg_attr.html.)

lamacase 9y ago

"I don't have these problems, therefore they are not real problems" 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.

fortythirteen 9y ago
> "I don't have these problems, therefore they are not real problems" What a major mischaracterization. It was the author that implied things were objectively bad. I stated that the subject is subjective, in that there are use cases where block comments are good.
- lamacase 9y ago
  What the author stated was: > I will argue that block comments are unnecessary, and in fact near-impossible to design and implement correctly (for my own pedantic notion of correctness) You might argue, subjectively or objectively, about the utility of the "notion of correctness" used here, but the author warns at the outset that this is the basis for the rest of the analysis. I ask again, what preface would the author need to write to satisfy your criticism? I think that it's worthwhile for the author to point out that you cannot create a block comment scheme without having some un-intuitive edge cases, and I'm curious what gave you the impression that the author was claiming an unwarranted degree of objectivity.
  - fortythirteen 9y ago
    He argued that future programming languages should get rid of them completely.
    - Athas 9y ago
      Yes, but based on an subjective judgment. I am the author of the blog post, and I tried to do my utmost to emphasize that my judgment here is highly subjective, using phrases such as "for my own pedantic notion of correctness", and "I cannot in good faith claim that [problems with block comments] occur all that often in practice". I try to make it clear that I'm not surprised, offended, or annoyed that most languages support block comments. How do you think I should have put my words, to make it clear that my opinion here is not intended as objective fact, but merely a subjective take on a language design question?