Robust software, for everybody.

Multiline comments in POSIX sh

Posted on

I realized one can use heredocs for multiline comments in sh:

1
2
3
4
5
 
cat <<'COMMENT' > /dev/null
if wip; then
        unfinished and broken syntax >
fii
COMMENT

plaintext

…​instead of:

1
2
3
 
# if wip; then
#       unfinished and broken syntax >
# fii

plaintext

What is going on: the language defines << as a redirect of the "here-document" type. After << you can put anything, and sh will use that as a token to look for on the following lines:

1
2
3
 
cat <<'bleh'
...
bleh

plaintext

Make sure to include the 'quotes' around the word, otherwise anything with a $ would get replaced just like a "double-quoted" string.

"bleh" works fine, like any word would.

But that example left as-is would print the string to stdout. To avoid that, we shove the contents to /dev/null. So it isn’t technically a comment, its more like a constant string that gets emitted and discarded.

Sure its hacky, but at this point what in sh isn’t? It even supports nesting!

1
2
3
4
5
6
7
8
9
 
cat <<'COMMENT1' > /dev/null

cat <<'COMMENT' > /dev/null

# ... code ...

COMMENT

COMMENT1

plaintext

I’ve never committed any code with this, just used while debugging sh code. Make sure to handle with care

25 messages on the fediverse

Reply on Mastodon | Lemmy

FizzyOrange@programming.dev
reply

Yeah but... Don't. Multiline comments are a bit of an anti-pattern at the best of times. This is a war crime.

TehPers@beehaw.org
reply

Multiline comments are a bit of an anti-pattern at the best of times.

If you're making this as a general statement, it varies from language to language. For example, CSS (and arguably HTML and Markdown) only supports multiline comments, and multiline comments are often used for documentation (as with jsdoc and, though only comments in the same way that heredocs to /dev/null are, Python).

But yeah, if you actually do this in Bash, wat.

thingsiplay@lemmy.ml
reply

CSS (and arguably HTML and Markdown) only supports multiline comments, and multiline comments are often used for documentation

Those aren't programming languages. Because, especially in HTML, a line end does not end an instruction and is just for formatting. So single line comments would be very awkward in HTML, so they had to use multi only. And because CSS is meant to be used close to HTML, I think they opt in to the same. JavaScript in example has single line comments again.

Does any programming language exist that supports multiline comments only without single line comments?

EuAndreh@programming.dev
reply

C89, AKA ANSI C famously only supports /* */, having // as a cross-pollinated idea from C++.

thingsiplay@lemmy.ml
reply

Good example, at least historical. ;-) I wonder why they never added single line comments before. I mean it took them quite a long time to do so. Languages before 1960 even had single lines too.

Edit: BTW it was common in C to write multiline comments to have them look like single line comments too, because that's easier to read and understand. Maybe that's why they didn't feel the need for, because in practical usage it could be replicated. In example as:

```c
/* Title
* description
* variables
*/
```

This could easily be replaced by single lines as:

```c
// Title
// description
// variables
```

TehPers@beehaw.org
reply

Both HTML and CSS (when together) are turing complete, and JSX syntax only supports HTML comments in many places.

JavaScript having single line comments isn't really relevant. Multiline comments are in heavy use there, arguably moreso than single line comments.

Edit: and I should add that "programming languages" is moving the goalpost. The person I responded to didn't qualify their statement to programming languages.

thingsiplay@lemmy.ml
reply

I don't think that being turing complete means anything in this discussion, because it does not change what the language is for and how its used and interpreted. HTML and CSS are not instructions for the CPU, they are markup languages describing text for humans, not compiling it down to execute machine code for CPUs.

TehPers@beehaw.org
reply

Again, the discussion was about multiline comments, not programming languages.

And regardless of all that, JSX remains one of the most used languages in the world and supports only multiline comments in certain contexts, and JavaScript as a whole uses multiline comments generously.

The discussion was around multiline comments being an anti-pattern, which is entirely untrue. They just serve a different purpose than single-line comments, and usage varies from language to language.

thingsiplay@lemmy.ml
reply

Edit: and I should add that “programming languages” is moving the goalpost. The person I responded to didn’t qualify their statement to programming languages.

I think from context it is apparent that we are not talking about HTML and CSS (which you brought this up yourself, not the person you responded to). I think there was no need to specify his statement was to programming languages, by context we know it is. Also we are in Programming.dev. What context do you need more?

TehPers@beehaw.org
reply

TIL programmers don't write HTML and CSS.

(I guess if all you use are LLMs to write it, maybe that's true.)

thingsiplay@lemmy.ml
reply

You understand the difference between a markup language to display text with HTML and CSS, and a programming language to execute programs. Right? And this has nothing to do with LLMs. I don't know why you are in an attacking position for no reason. I didn't want hurt anyone, just discussing here.

TehPers@beehaw.org
reply

I don't know why you are in an attacking position for no reason. I didn't want hurt anyone, just discussing here.

You are being excessively pedantic over a topic that has absolutely nothing to do with the discussion. I don't know how you want me to respond to these comments.

As a reminder, what I was responding to was whether multiline comments are an anti-pattern, not whether HTML+CSS is a programming language.

FizzyOrange@programming.dev
reply

The fact that CSS only supports multiline comments doesn't mean multiline comments are good, it means CSS is badly designed.

TehPers@beehaw.org
reply

It means neither of those, actually, just that CSS supports only multiline comments.

Multiline comments remain prevalent across ecosystems though (like in JS and Python). If you believe they're bad there too, that's fine, but the fact is that it would be an anti-pattern to go against those established standards.

thingsiplay@lemmy.ml
reply

I think this solves an issue, that's not an issue at all and makes it more complicated and harder to read. What do I mean by that?

It requires more text and exact correct syntax of multiple elements. It makes it harder to see where the start and end is, and one has to look for any lines that could potentially be a comment in a heredoc. The syntax highlighter does not show this in comment color. Bash still executes those lines to read the "comment", as it thinks its normal code. In example variables can still be expanded in heredocs. Other tools removing comments from script to count lines would be fooled too.

Compare this to a single hashtag symbol in the beginning of each comment. That's all. This is also good practice everyone understands. From practical point of view, why would anyone use heredocs for multi line comments over single line comments?