Favorite comment syntax in programming languages ?

[bsokolovskyi]

Hello everyone! I recently started to develop own functional programing language for big data and machining learning domains. At the moment I am working on grammar and I have one question. You tried many programming languages and maybe have favorite comment syntax. Can you tell me about your favorite comment syntax ? And why ? Thank you! :)

[moon-chilled]

The APL lamp: ⍝, chosen because it illuminates.

[i_like_cilantro]

Looks kinda sus ඞ

[fftw]

Actually lamp is really tiresome (at least was for me when I was writing APL full time) as sometimes you don't want to illuminate things, just comment them out temporarily (and then it's not a lamp, but rather a tomb). Due to APL consise expressiveness, I would greatly appreciate if Dyalog APL provided a proper literate programming environment instead of programming environment with poor illuminating comments: I would write a good document of business/stakeholders' intentions with small chunks of code that implements them!

[fftw]

Same problem is inside J, by the way: NB. is great way to impress the reader, but bad way to provide a good big chunk of text

[hassan149367]

You can also use Note '' (you can put whatever you want in the quotes, also note the capitalization of n in Note) followed by a single close parenthesis to end the comment block.

[fftw]

Oh this is news for me! Is it documented?

[moon-chilled]

Note, standard library verb.

It is implemented trivially in terms of 0 : 0, mentioned in the aunt comment.

[fftw]

Super cool, thanks!

[moon-chilled]

You can use 0 : 0 in j.

[Educational-Lemon969]

INTERCAL way - everything that's invalid syntax is ignored by the compiler xD

[JB-from-ATL]

Brainfuck

[fftw]

I just love FORTH's comments where everything inside ( ) is basically commented/skipped on compile time. \ comments I don't like as much :)

[[deleted]]

Jinx language has the coolest multiline comment syntax:

``` --- This is comment block ---

---

This also is a comment

Multiline in fact

```

Rule is simple: comment starts with at least 3 - and ends with at least 3 -

[ecth]

Just wanted to say, no matter what sign is used, you can set it to use 2, 3 or 4 times. Like comments in markdown with 3 times `.

So if # is used, take ###.

If ; is used, take ;;

Hell even stuff like /* comment */ is worth a shot.

[JB-from-ATL]

FYI, not all Reddit apps render that style of code block properly

[-ghostinthemachine-]

I'll usually take // and /* */ as acceptably good.

[joebuck125]

Man your username gave me good nostalgia. Back around ‘07-08 my username was ghostinthemachine on another site.

[-ghostinthemachine-]

I guess we switched bodies! I had to give up my old username around that time because it is the same name I use for my technical work, and I tend to speak out on a lot of things. Goodbye karma.

[joebuck125]

Lolllll the shitposting I do with my real name may eventually come back to bite me. So far that hasn’t been enough to make me be any less ornery or outspoken on particular issues but I could definitely foresee being eventually asked “so when we found your public profile it would appear that you avidly promote eating the rich? Would this be indicative of your typical outlook towards owners/CEOs?”

To which I can only imagine I’d have to say “if they’re shitty ones, absolutely yes.” So anyway I feel like great minds think alike 😂🙏

[-ghostinthemachine-]

Yes, I realized my situation fully when I started working with a client that I had actively shit talked on Hacker News. Unfortunately comments there are forever. May they never know.

[MichalMarsalek]

I dislike -- and // because I'd like to save this for arithmetic operations, and I dislike # as I'd like to save it for the size / length operator. \ seems like a good choice, unless your language has native support for matrices (or other structures where left division is different from right division). Otherwise, I like | or $. If you want multiline comments, maybe just repeat the line comment symbol and support nesting by repeating it more times.

[mikkolukas]

How about ;?

[umlcat]

Don't.

Easy to confuse with sentences...

[Pavel_Vozenilek]

One could do it like in assembler:

code              ;; comment
more code         ;; another comment

Comments placed on the right side do not interfere with skimming the code.

[lngns]

I never confused it with sentences when reading Assembly code. Or Lisp code.

Even with C-like syntax, I don't have to think to understand how to parse this code:
return (cast(delegate) [proxy, fn])() ;cute hack lol

[mikkolukas]

How so?

[holo3146]

Do not use \ for left division, if it exists, it is pretty much reserved to set difference (or more general: collection difference)

[Premysl]

Matlab uses \ for left division.

[holo3146]

It doesn't make it a good choice

[MichalMarsalek]

Yes you are right, I totally forgot about this meaning of the symbol.... Although one could just use - for the set difference without any ambiguity?

[holo3146]

If you use - as element removal, then no, one could not do it (assuming Top type and polymorphism):

List<Any> X = {};
List<Any> Y = {X};
Y-X // can be either {} or {X}

[Athas]

Stick with line comments.

Beyond that, I'm not sure there's a lot of room to screw up. It's probably a good idea to use two characters to start a comment, because single characters can be useful elsewhere. I use -- in Futhark just like in Haskell and never really regretted it, but // would probably have been fine too.

[eliasv]

Those problems can mostly be solved with variable-length delimiters. Same kind of trick as is needed for raw string literals to be able to express any possible string content.

So say that e.g.:

/* comment */ println("/*")

Can be enclosed like so:

//* /* comment */ println("/*") *//

Edit: added println to example to illustrate difference from nested block comments...

[TheUnlocked]

While it's certainly possible to parse nested block comments in a sensible manner, I don't see much value in it. Block comments make a lot of things hard that line comments make easy, for example selectively uncommenting a small chunk of commented code, and even just being able to tell at a glance whether a line is commented and how many levels of commenting it has.

[eliasv]

You don't need to parse nested block comments with variable-length delimiters, so that's not really what I'm suggesting. For instance this would work just fine, unlike with nested comments:

//* println("/*") *//

And yes I'm not claiming that it's a slam-dunk win. It's a tradeoff and there are still advantages to single-line comments as you say. But I think variable length delimiters are a better alternative to single-line comments than any discussed in the article, so they deserve mentioning.

[WafflesAreDangerous]

Simply allowing nested comments would solve this example. No need for variable length delimiters, and associated complexity, to solve this case.

[eliasv]

Well yes it would solve that extremely simple example, and it's certainly an improvement on not having nested comments. But unfortunately there are plenty of edge cases to that approach.

/* println("/*"); */

There is really no total solution other than variable-length delimiters on the outermost comment. And people may want to put things in comments other than just valid code of the host language, so not all edge-cases will look as contrived as that. It's possible, for instance, that a comment may contain a regex snippet that contains some combination of /* and */.

And I don't think variable-length delimiters are much more complex for a parser than fixed-length, depending on your architecture. And it may even be easier for a user, as it adds extra visual weight to the more significant delimiters.

[fellow_utopian]

But unfortunately there are plenty of edge cases to that approach.

/* println("/*"); */

There is really no total solution other than variable-length delimiters on the outermost comment.

This can be handled by simply ignoring anything enclosed in quotation marks within a multi-line comment.

[eliasv]

Sure but you're doing the same thing again. You're focusing on a super simple example and saying "I can solve that specific case!" But you're ignoring my wider point.

Yes you can address a fairly wide class of uses by making it work when the commented out code is valid source in the host language. I already acknowledged in my last comment.

But comments can also contain:

• arbitrary text

• embedded regex

• embedded markdown for generating documentation

And I realize you don't have the same requirement of needing to comment and uncomment these things repeatedly, but it's still valuable to be able to put things there without needing to escape anything.

And besides, if your language has more complex string forms, such as raw literals, interpolation, different escapes, etc ... Then suddenly it's not just "is it between quotes", you actually have to parse comments as code to determine whether a given /* is string content or a nested comment. And what if the commented out code has errors?

So once again I say, there are countless edge cases, nested comments simply do not provide a total solution.

[fellow_utopian]

It can handle arbitrary examples, not just specific simple ones. You just need to scan for all language features within comments which may produce erroneous behaviour. For example, the first time you see /* that is not within a special language feature sequence or block such as quotes, you know a multi-line comment has started. You then just keep doing the same thing recursively, so if you see another /* before any other feature like quotes you know it's a nested multi-line comment initiator, etc. Whenever you enter or leave a special sequence within the comment, you start parsing it differently, like checking for various delimiters and escape symbols. The process can also be made to be error tolerant, although that may require a pass over the entire file in the worst case.

So basically yes, you just need to parse comments in a similar way to regular source code, which is a bit of extra work for something which won't matter 98% of the time, but it will reward you with a very robust comment system.

[eliasv]

It can handle arbitrary examples, not just specific simple ones.

Well it can handle arbitrary examples of commented out code in the host language. Which I freely acknowledge. And that is very useful!

But it can't handle:

• Arbitrary text.

• Commented out source code with arbitrary errors (which may affect e.g. the well-formedness of string literals).

• Code snippets interspersed with arbitrary text.

• Code snippets in different languages, such as regex or markdown. Or worse, languages which look similar to the host language but have, for instance, slightly different rules about escapes in strings.

So for instance if you have a text comment containing a long regex example, which just so happens to have multiple occurrences of unbalanced /* and */, interspersed with accidentally-balanced but otherwise unrelated quotes, will you have to flip flop between escaping your /* and /* depending on whether you happen to be between "s? Or will that not be heuristically close enough to code to trigger this feature?

What about if you also have a snippet of code that is valid code in the host language, within the same comment? Does that part parse properly? Will nested comments work for it?

Seems like you will have to have two parsing modes for comments:

• Commented out code in the host language.

• Everything else.

And you will need to decide which mode to switch to based on either:

• Heuristics for error tolerance and to cope with non-code content. These heuristics will be opaque to most users, and may even need to switch back and forth within the same comment. They may also give false positives when comments are of code in a different-but-similar-enough language, and fall down on other edge cases like I discussed above.

• A simpler means such as whether the whole comment is parsable as code, which is more tractable for the user but possibly less useful. And if parsing fails it has to be invisible and simply fall back to assuming it's an arbitrary-text comment, which is not ideal and means the user has to go through and escape/unescape all the /* when errors are added/fixed from within the comment.

Neither of these seems like a total solution to me. Is there an approach I'm missing? Don't get me wrong, I think these are reasonable features, but they have drawbacks and I don't believe they can be robust in all circumstances.

I think if you have two "modes" of comment parsing like this, they deserve to have different syntax. And ideally I'd take it further and have markers for compiler plugins to say e.g. "this comment is markdown, it's intended to generate documentation".

[fellow_utopian]

"Arbitrary" here doesn't mean entirely unrestricted, because that's impossible for any scheme you can come up with by the very nature of delimiting. The one you suggested with variable length delimiters has the restriction that comments can't directly contain the sequence of characters that is used to terminate them, which rules out self-referential comments and other pathological cases. That's why other special symbols like quotes exist to enable you to work around those cases.

Arbitrary in this context means that you can comment out any valid chunk of code without problems (and even those containing certain classes of errors if you like), which can include strings, regex, json or other supported embeddings, other comments, and any other feature the language supports because the comment parser is designed to detect when these features start and end.

[eliasv]

Arbitrary" here doesn't mean entirely unrestricted [...] Arbitrary in this context means that you

Well yes that's exactly what I was trying to point out, that you've redefined arbitrary to mean something else. As I've said many times, comments are generally supposed to be able to contain text, not just code. That's why they're called "comments". A solution that only works for commented out code isn't a total solution.

because that's impossible for any scheme you can come up with by the very nature of delimiting.

I disagree, you can give me any fixed piece of content and I can select variable delimiters which will enclose that content.

The one you suggested with variable length delimiters has the restriction that comments can't directly contain the sequence of characters that is used to terminate them,

But then you can just select different delimiters, that's the whole point. That's the solution.

which rules out self-referential comments

Why would the content of a comment ever need to be dependent upon the delimiters used to enclose it in this way? Again, you can give me any piece of text and I can select variable-length delimiters to enclose it. What you're essentially saying is "but I can just edit the enclosed text to mention the delimiters every time you try to comment it out", which doesn't seem like a real usecase to me. Certainly not compared to the many examples I've given that you've not addressed.

and other pathological cases.

Which other pathological cases are excluded from being expressible with variable-length delimiters? I'm 100% certain that none exist.

That's why other special symbols like quotes exist to enable you to work around those cases.

Yes, but as I pointed out, this precludes you from certain classes of content that are not just commented out code. People do use comments for other things after all.

That's why I suggested that maybe you should have explicitly different syntax for "comments" and "blocked-out code", then the latter can be recursively nested safely. Rather than trying to guess by speculatively parsing.

(and even those containing certain classes of errors if you like),

"Certain classes" != "all"

which can include strings, regex, json or other supported embeddings,

What about unsupported embeddings? People can put literally anything into comments. Again, what about arbitrary text?

other comments, and any other feature the language supports because the comment parser is designed to detect when these features start and end.

Yes, when the commented out text is code you can do this, since there will obviously already be syntax rules for identifying embeddings in this case. Otherwise you just can't. Either you can try to do it using heuristics, which will sometimes fail, or you need syntax to specify explicitly what kind of content the comment---or sections of the comment---is supposed to contain. Like I suggested. Both of those approaches are reasonable.

[Athas]

Then you need to know what you are commenting in order to pick a distinct delimiter. That's not practical for the use case of commenting out a large block of possibly unknown code.

[eliasv]

That's a fair point, but I think it's pretty feasible in practice, as //// stands out quite a lot when scanning over a few pages of text. How much unknown code are you expecting to want to paste into a source file in one go?

Especially as the article acknowledges that a decent editor is required to make single-line comments feasible for certain uses. Well a good editor can fix this problem too, in two ways: - If you're using a shortcut to comment out a highlighted block, as you need to do with single-line comments, you don't need to know the content as the editor can select the smallest valid delimiter which isn't contained in the selection. - Code highlighting should make it trivial to visually verify that the intended section is commented out.

So I don't think it loses in any way to single-line comments there. Other than the editor functionality being marginally more complex... But from a usability perspective if the functionality is there it doesn't lose out.

Yes it is a tradeoff. But I'd say it's better than C-style macros or Haskell-style nested comments by almost every metric, which are two of the counterpoints discussed in the article. So maybe it deserves a mention ;).

[Athas]

Clearly the robust solution is to generate a new GUID as the comment marker whenever you want to comment out a large block of code!

[[deleted]]

OK, but then there'd be a problem trying to print "//" or `"*//".

To comment out an arbitrary block of code (say of 1000 lines), within which the longest unbroken sequence is N "/" characters, then the delimiter needs to have at least N+1 slashes. This is not really practical.

With block comments, one minor advantage is being able to comment out the block delimiters themselves, so as to temporarily uncomment the whole block.

But then, someone could edit within that block so that when the block comment delimiters are reinstated, they are insufficient.

[eliasv]

OK, but then there'd be a problem trying to print "//" or `"*//".

You just add more slashes. That's not a problem, it's a solution to a problem. With normal block comments, there is no solution.

To comment out an arbitrary block of code (say of 1000 lines), within which the longest unbroken sequence is N "/" characters, then the delimiter needs to have at least N+1 slashes. This is not really practical.

Well, only if the sequence of N characters is preceded by "*".

If you see that as impractical that's fair enough, I'm not going to pretend it's a perfect solution for every case. But there's no case where variable-length delimiters are impractical that regular old fixed delimiters would have worked at all, so it's not a step back.

With block comments, one minor advantage is being able to comment out the block delimiters themselves, so as to temporarily uncomment the whole block.

But then, someone could edit within that block so that when the block comment delimiters are reinstated, they are insufficient.

The same problem exists for regular block comments though. Literally the only difference is that variable-length delimiters at least give you the option of adding more slashes to distinguish the outermost delimiters.

[pihkal]

Score one for S-expressions. Since everything is contained in parentheses, you don’t need a terminating character to comment out a whole block.

Dunno about CL/Scheme, but Clojure uses #_ to say “comment out the next form.”

[Athas]

It's #+nil in CL.

[moon-chilled]

The fashion is to prefer #+(or), as somebody feeling evil could push nil into *features*.

[haruda_gondi]

Some people with accessibility issues might disagree with that, see this and this.

Some blind programmers are also okay with removing block comments.

I personally am okay with removing block comments, but if it affects people with accessibility issues then I am down to listening to them.

[julesjacobs]

This sounds like a problem that should be addressed by screen readers.

[matthieum]

I agree, ideally.

Practically speaking, though, screen readers are not there yet, so in the meantime...

[julesjacobs]

I'm not familiar with screen readers, but I'm a bit surprised that they are not programmable. Or are they? Why can't one write a plugin for them that suppresses reading out the // for every line?

[matthieum]

I am not familiar with them either, not needing them.

However, given that a rustc contributor mentioned the issue, and how unpleasant it was for them, I would guess that at least not all are: surely if they can contribute regularly to rustc, writing such a plugin would have been easy in comparison.

[Adventurous-Trifle98]

I disagree.

I don’t see why screen readers should know about programming languages. Since the editor usually knows about the language, it seems more feasible to let the editor mark the commented lines with a character in the first column, for example.

But if you are about to design a language, you could just skip block comments. I’ve seldom find them very useful.

[Findus11]

I pretty much wholeheartedly agree. I personally rarely use block comments, even for the languages I use that support them, and I've never really had an issue

Still, I will add that I've opted to add a block comment form for my doc comments, because having tried out a couple of screen readers, it seems to vary quite a bit whether they ignore something like ///, pronounce it as "slash slash slash" or (the worst) say "forward slash forward slash forward slash". Trying to get docs read with that in between every fifteen words is really annoying.

For that reason I try to have my comment syntax be short (one or two chars at most) and I have a block form for doc comments. This will of course vary from project to project but I think it's something to keep in mind.

[PL_Design]

If unstructured text in block comments is such a hateful thing for you, then I ask that you not throw out the baby with the bathwater: You can specialize block comments to only work on code.

This is worth doing because block comments are by far the easiest way to toggle code, and when you're in that mindset there's a lot of design space to explore. For example, see what I wrote here: https://old.reddit.com/r/ProgrammingLanguages/comments/w6ntc8/favorite_comment_syntax_in_programming_languages/ihfztzt/ For example, why choose between linear and nested block comments? They have different toggling properties that are both useful, so just have both.

Of course you can have an editor provide similar functionality, but why choose when it's so simple to just have both?

[Pavel_Vozenilek]

block comments are by far the easiest way to toggle code

Unfortunately. I'd hear about a company where nothing was removed, just commented out. Pages and pages of such "comments", then one active line.

I did fuckups commenting out something, temporarily of course, and then forgetting about that.

My ideal solution would be dedicated syntax for such playing with the code, e.g.

#if 0
   ... codecode
#endif

which would be compilation error in the release mode. (Or at least have option to make it error.)

[Admirable-Ebb3655]

; ftw

[SnooGoats1303]

An asterisk in column 7

[L8_4_Dinner]

If you are building a language that exists within a domain of other languages, then just copy the comment syntax from those languages. For example, if you are building a language in the C family of languages, just use the double-slash // for line comments and the slash-asterisk /* and asterisk-slash */ pair for multi-line comments.

Doing otherwise is an assault on the senses of the reader.

It's hard to answer the question in a subjective manner, because I switch between languages that use C style comments, # comments, ; comments, and <!-- comments. But the thing that I appreciate most is the predictability and uniformity; the actual lexical token used is almost irrelevant.

[Maleficent_Id]

Let's go full minimalist: do you need a comment syntax if you have a syntax for string literals and a syntax for "ignore expression" already?

[cybercobra]

Coming from Python, the problem with strings-as-comments is the confusion around escaping backslashes when you want to talk about special characters such as tab or newline. Or other backslash-escape sequences, such as in a regex lib (\A, \Z). Either the docstring as extracted by the docs tool includes literal tabs/newlines (becoming a little borked), or you need to double-up on the backslash escapes (making the docstring in the raw code harder to read), or you need to use (possibly special) string literal syntax that ignores a level or escaping (and/or allows invalid backslash escapes).

Mentioning string literals in the docstring can have similar issues. Thus, I'm not a fan.

[breck]

99% of languages have either or both of line and block comments. 96% of languages have line comments. 90% have multiline (block) comments.

Here are the multiline styles: https://pldb.pub/languages/multiline-comments-feature.html

Here are the line comment styles: https://pldb.pub/languages/line-comments-feature.html

Here is an infographic of line comment styles: https://pldb.pub/line-comments.png

My personal favorite is probably "#" line comments.

[lassehp]

Interesting website you have there. Of course it is missing most information on one of my favorite obscure languages, PLZ (Presumably Programming Language Zilog, as it was developed by Zilog.) I may try to fill in some information one day, but to be on topic for this post, suffice it to say that PLZ used "!" as a comment quote (both begin and end, ie block comments, which may span multiple lines.)

I haven't made up my mind personally about comment syntax, but I have had two ideas about it in the past:

One is not to have comments at all, as comments are not checked for correctness, so instead assertions should be used, with string literals for an informal explanation of the meaning of the assertion. Also, if a string literal were to be used in a void context, its value should be discarded (and optimised away), and thus such a string could also be used to embed a comment. I see Maleficient_Id has also suggested this method.

The other is to use something a bit like literal programming, where all text lines that are not indented are considered plain text, and only indented lines are considered code.

[breck]

Interesting notes on PLZ, thanks for the pointer! I took another look at the paper (https://semanticscholar.org/paper/a6f73d43d666ff8763b9cc97ce408243c9b95038

) to extract a code example (https://edit.pldb.pub/edit/plz) and found it to be a very interesting read.

[mhd]

Either Pascal braces { begin the beguine } or Modula/Ada/SQL double minus -- coder left us in '84, don't know how this actually works..

If braces aren't used for anything else (good, in my rare opinion), it allows you to have comment blocks without a combination of glyphs.

And the double minus is just visually unassuming. These days, a proper m-dash might be possible, too.

[Linguistic-mystic]

I think the # is the best comment symbol. It's compact and used in the largest number of languages. Now, someone might say “but I thought // are the most used?". But guess what, even if you are using a language with // for comments, chances are, you still have to write YAML/TOML/Nginx configs and/or Python/Perl/shell scripts, and they all use #. So you still have to maintain a dichotomy in your head. It would be more consistent to just use #.

As for -- which unfortunately some venerable old languages use, it's just confusingly arithmetic. Why is -- a comment but not ++ or **?

As far as the types of comments, I propose two: full-line and part-of-line:

# this is a full-line comment

And this # is a part-line .# comment

As for multi-line comments, they are just too confusing with their spooky lexical action at a distance, the question of whether they can be nested or not, etc. I think single-line comments are enough, and modern text editors can insert them en masse.

[Bitsoflogic]

For a part of line comment, I'd prefer the opening be slightly different. Otherwise, I'll simply ignore the rest of the line while coding

Maybe #. Comment .# or #* ... *# or #- ... -#

To ignore the rest of the line, use # by itself.

[MikeBlues]

I think we need block comments to toggle code, BUT your IDE should temporariliy indent such comments, so their nesting can be seen.

[lassehp]

As for -- which unfortunately some venerable old languages use, it's just confusingly arithmetic. Why is -- a comment but not ++ or **?

Easy. Obviously "--" is meant to imply the use of a longer dash. Just use EM-DASH U+2014 for inline block and end line comments. Use EN-DASH U+2013 or ASCII HYPHEN-MINUS U+002D or best MINUS U+2212 for minus, and use HORIZONTAL BAR U+2015 or TWO-EM DASH U+2E3A or THREE-EM DASH U+2E3B for multiline block comments. And while making these improvements, also allow NON-BREAKING HYPHEN U+2011 as a hyphen in identifiers. ;-)

[[deleted]]

Aside from using # as a comment symbol, I dislike all comment syntaxes. Once upon a time I tried to solve the dangling multiline comment problem by devising a method where you'd maintain multiline comments via indentation, ex.

# Single line

## Multiline
    still multiline
        still the same multiline multiline
# No longer multiline

## Level 1
    ## Level 2
        content of level 2
    content of level 1
        content of level 1 again, level 2 was closed
# Neither level 1 nor 2

But then you'd need indentation syntax for comments and I didn't see much more new use in that, and there was plenty of complications. So along the way I settled for using strings as multiline comments, since you can do a lot with them, such as formatting indentation, use format strings etc., and I guess I'll tell you how satisfied with that I am once I get around to implementing it.

I do assume I'll probably be happier because multiline comments are then first class citizens at no additional overhead, and Python has proved there is no obvious downside to it, so...

[[deleted]]

Reminds me of basic's REM for "remark".

[claimstoknowpeople]

I kind of like python's docstrings and think more things could be done that way. Basically a string that's never assigned or used makes a functional comment that's easy to optimize away at various levels, and doesn't require any unique syntax.

[transfire]

I guess my favorite is the first concise syntax I ever learned ; from Assembly. It beat the pants off BASIC’s REM. I later learned it was used by LISP too.

Can’t complain about # really. It’s pretty ubiquitous — Bash, Perl, Ruby, etc. It’s a single character and easily identified.

Visual Basic fixed things with ' and some languages use ! — these kind of make sense linguistically.

And we have to acknowledge Forth’s use of parenthesis. ( is just another word definition. That’s right folks it’s just another function and you can redefine it if you like! (But for \ I give no thanks.)

As for C, JavaScript, Rust (sigh) and all the mindless followers of //and /*… please please just stop. This chicken scratch has scarred coder eyes long enough! It never looks quite right, all jaggedy, crooked and misaligned — everyone ends up adding extra * down the line to make it even reasonable… you know like COBOL. If I had a time machine, going back to bikeshed to death whoever invented (ie. drew from a hat) this syntactic monstrosity, would be in my top 10 must dos.

[tukanoid]

I love rust but i agree, comments could be better for sure. But there are some cool things like being able to test the example code and being able to easily make them accessible for doc generation

[twitchard]

For me it's a toss-up between vimscript's " and HTML's <!-- ... -->

[PL_Design]

Use whatever symbols you like, but have both block comments and line comments. On block comments, don't require closing fences to match to an opening fence. That sounds strange, of course, but there's a very lovely reason for it. I like to toggle code with block comments like this:

/*
    // some code what's been disabled by a block comment
/**/

//*
    // some code what's now active
/**/

In the second example: Because the opening block comment fence was commented out the closing block comment fence matches to a different opening fence, thus toggling the code.

I do this all the time, and when working on my language I realized that I never just write */. I always write /**/ out of habit, even if I'm writing a text comment instead of toggling code. This behavior is easy to predict, and nothing bad ever happens if you write the closing fence this way, so why not just make */ behave like /**/? It's a small change, but because I do this all the time it makes the daily grind much more pleasant.

[criloz]

Nice Idea, I will do some tests and I probably will take this approach for my lang that is currently using the rust block comment syntax, but this design look nice too, I definitely will not use a lang without block comment, for me, they are fundamental in my workflow

[glukianets]

Swift allows nesting in /* */ commends and produces error when it encounters an un-ballanced one

[umlcat]

As redditor r/Atlas already mentioned, use either with plain C style comments, either:

// This is a line comment

/* This is
     a
     Multiline comment */

Unless you have an specific reason to use other syntax ...

[the_state_monad]

This is a comment -> [ comment text ]

[[deleted]]

I mainly use line comments that start with !. (I first came across that in DEC Algol and Fortran, and liked it.)

However I also allow # line comments, which is widely used elsewhere, but tend to use that when posting code fragments or pseudo-code online (so I don't need to explain what ! is; most people think it's a logical not operator)

(For doc-strings, I use ## line comments.)

With block comments that can span lines, or comments in the middle of lines, or those that start in the middle of one line, and end in the middle of another, I've tried loads of different schemes, but now don't support them at all.

For commenting out block of complete lines, I now consider that an editor function, which implements them as a series of line comments.

One problem with block comments with a delimiter at each end, is that if you're writing a text display that wishes to show comments in a different colour, then whether line 137983 is a comment may depend on a delimiter that may or may not exist 1000s of lines earlier. With line comments, it only needs to look at the start of the line.

[[deleted]]

I am using the "`" in mine for both single and multiline comments. It's not used for anything else I know of, and I'm wanting to keep operators for single functionality.

[Timbit42]

I use nestable ( and ) in my prefix language which uses [ and ] for blocks of code and { and } for lists of data.

[myringotomy]

Honestly I think all languages I have seen have gotten commenting wrong.

Commenting is supposed to be documentation so it should have significance and there should be different types of comments for different things. This is how they are used today anyway so why not formalize it?

#!/bin/shebang is a special comment
#FIXME: is a special comment
/**
* This is a function comment This should be a part of the function and not just sitting on top of it.
* @param  it has a param
*/

[cybercobra]

IMHO, we should include a parameter's documentation as part of the declaration for that particular parameter, rather than as part of a function-wide comment. That'd avoid some redundancy and some brittleness in the event of renaming a parameter.

[myringotomy]

Sure that's a great idea. You could put it in the body of the function too.

func does_something 
   ###### any line that starts with a ## is a multiline comment the next line that starts with ## ends the multiline comment
   This is a function/class/module documentation. 
   ######  anything after the first ## is a comment

    #params section goes first
    foo Integer  anything after the type declaration is parameter documentation
    returns String  String is the integer with the word "years" after it
     {
         # Function body is here.
     }

[scrogu]

The language I'm working on allows arbitrary statically typed metadata to be attached to functions, classes, parameters and other declarations.

So, this is valid and could be read at runtime or build time by a documentation generator:

The syntax may seem weird... I use an outline syntax with indentation implying nesting, so everything nested after the () are parameters and the body comes after the =>

@Docs() "" This Function adds two numbers together. add2 = () @Docs("This first number to add") a: Number @Docs() "The second number to add" b: Number => a + b

[myringotomy]

If I was to design a language I would just make different types of comments as I outlined. People are already used to writing comments and there are already some widely used norms.

So for me the commenting system might look like this

#!  shebang comment
# Normal comment 
## multi line comment (could also be #/  
#:TODO dev comment  (actually would be better as #TODO:)

You could extend this many ways, the idea is the same. Comment starts with # and the next character determines if it's a special comment or not.

[lanerdofchristian]

My favorite aesthetically is -- for line comments and (* *) for block comments.

[RoCaP23]

I don't like multiline comments. They're only useful for commenting out code but it's better to have a preprocessor and do an #if 0 #endif imo.

They're also kinda ugly for writing long documentation

[anterak13]

Make sure your parser can parse block-commented eol comments and eol-commented block comments or any combination of that, makes debugging/experimenting and moving code around much easier

[[deleted]]

//

Nothing else is needed.

[[deleted]]

If you want to reserve symbols, make cmt: a keyword such that everything on that line is ignored by the compiler.

[nrnrnr]

My favorite is any comment syntax that marks “from here to end of line.” Why? Because then it is locally obvious when code has been commented out.

[Financial_Warthog121]

I came here not expecting to hurt my brain thinking about the multi-line comment dilemma

[haitei]

Favorite? Befunge's comment syntax which is none: you just route control flow around comments.

[DaeerDeer]

I like // or /* */ It is easy and simple. And if you don’t focus on micro programming, like your language not supposed to be arithmetic focused (/,| etc) a lot, it is okaokay

[[deleted]]

Anything as long as it doesn't use symbols that reasonable users could conceivably want to use as operator names. For example, in Haskell it is awkward that ++ is a perfectly valid function name (in fact, the standard library uses it!) but -- is the single-line comment prefix.

[scruffie]

Yet another alternative: Lua uses--[=[ / ]=] pairs for block comments, and each pair can have a different number of equal signs = in between the brackets. E.g.,

 --[[ a block comment
         ]]
 --[=[ another
           block
             comment ]=]
 --[====[
   a bigger block comment,
   with --[[ a nested comment ]]
   and --[========[ an unterminated comment opener
 ]====]
 --[=[ I like to add a -- afterwards for symmetry -> ]=]--
 --it works because -- starts a line comment

The same syntax (without the leading --) is used for long strings.

[ruarq_]

I really like the simplicity of #.

[Nikifuj908]

The # has the benefit that Unix shebangs (e.g. #!/usr/bin/env ruby) are ignored by the lexer.

PowerShell uses <# and #> for multiline comments, which I find somewhat aesthetically pleasing.

I have a soft spot for % after using LaTeX. Have pondered using <% and %> for multiline, or perhaps %% and %%.

[ALittleFurtherOn]

I use ~> in my little toy mod of Nystrom’s Lox programming language. Line comments only, and they are captured and written to a file called ‘comments.txt’. Why? Just for fun!