4

I'm trying to convince the designers of a language that multi-line comments with an arbitrary start and end are important, and should be included. Currently there is only a "comment-to-end-of-line" primitive.

Their line of argumentation reminds me of what some say about why you should use spaces instead of tabs. Basically that editor features can pick up the slack and remove the requirement for a different construct. (So if you wanted to comment out more than one line, you'd select what you wanted and run a macro of some kind...to add or remove a to-end-of-line comment to each line. I just read that this feature exists in Visual Studio, despite C/C++ offering a multiline comment.)

Other suggestions about removing blocks of code from execution wind up being things like "cut the code out, try it, and use the redo queue". I think this is not a very easy way to keep track of "invisible" information you might want back, and redo queues are quick to lose information the moment you hit even a stray key on accident. So this does not sway me.

I can live with the space vs. tab thing and putting that on the editor, and it's now pervasive. But to me this is different, and I'm dissatisfied with these answers. For me, being able to comment out code with just a start and end marker like /* and */ is extremely useful. Passing the buck to editor magic doesn't let you position your starts and ends arbitrarily (how would you comment out the middle of a line if all you had was //?) And I also don't like leaning that much on editor features.

Sorry to ask a question with overtones of an opinion poll, or about something subjective. But what I'm looking for are any more objective arguments I am not thinking of, which could provide more ammunition backing this feature I think is important. (Or I guess I could accept a powerful argument favoring NOT having a multi-line comment format, which overrides my strong desire to have it... I'm not putting high odds on that, though.)

6
  • 1
    relevant question stackoverflow.com/questions/397148/…
    – Rotem
    Commented Apr 22, 2014 at 1:06
  • @Rotem Good link (wouldn't think that would be an SO question but more something for programmers.SE) As it happens, a similar excuse of just using multi-line strings exists for this language, which has {curly braces as string delimiters}. Because the string delimiter is asymmetric, it can nest. However, because it has a code-as-data paradigm, that only kind of works in evaluation contexts (between complete expressions), and not in data contexts. :-/ I still really want multiline thrown-out-by-the-parser comments. Commented Apr 22, 2014 at 1:42
  • Curly braces as string delimiters? Does that mean it uses " for statement grouping?
    – Rotem
    Commented Apr 22, 2014 at 1:45
  • @Rotem Square brackets. Feel free to discuss with us in Rebol and Red if you are interested in some of the design choices; some of which are extremely interesting. (I myself like being able to open and close blocks without hitting shift...) Commented Apr 22, 2014 at 1:53
  • @HostileFork That's an old question that predates Programmers.SE. As I understand it, it can't be migrated here now.
    – Izkata
    Commented Apr 22, 2014 at 2:30

4 Answers 4

12

I don't see a compelling argument here for non-line comments, and personally I cannot remember the last time I've used one.

  1. Comments in and of themselves are decreasing in frequency, and should be focused on explaining why code is doing stuff. That is done using line comments.
  2. Leaving commented code in your codebase is an anti-best practice with the ubiquity of source control systems (and distributed systems make it even easier).
  3. Multi line comments aren't going to make or break your programming language.
  4. We're not using stone knives and bearskins anymore. When I first started, not a few programmers used vi (not even vim) because things like syntax highlighting were a crutch. Programmers use tools, take advantage of that.
7
  • We are using stone knives and bearskins. If I have a variable declared in one place referenced by name 999 times, why does it require touching 999 sites across files to adjust that name? A graph-based editing tool could have formalized the link to what I meant to specify (the way normalized databases use primary keys), and then be able to change the name at the declaration site if that name change clarified things. Maybe leaving the old name on as deprecated to help with indexing and binding? But when in editing-programs-with-the-same-thing-you-write-email Rome, why lose multiline comments? Commented Apr 22, 2014 at 2:47
  • 5
    @hostilefork - sane editors have had refactor/rename for what? 25 years now? You lose sub-line comments (because let's face it, multiline comments are a breeze with single line comment syntax) because the designers want to spend their time on something that actually does something for their language.
    – Telastyn
    Commented Apr 22, 2014 at 2:59
  • Great editor feature...I like especially how it touches callsites in clients of APIs of documents I don't have open or access to on other people's computers (as well as how much I like having 999 + and - Git diffs in my own files for a single edit!) I'm sorry, stone knives and bear skins. Programs are best thought of as graphs and structure, just as building the Boeing 777 in MS Paint would be ridiculous; you need something that can actually model what you are trying to depict. Commented Apr 22, 2014 at 3:01
  • @HostileFork: that's how the Intentional Domain Workbench works, for example. Also, IDEs have been based on transformations of semantic trees for a long time, the text editor is just a projection. Commented Apr 22, 2014 at 3:12
  • @JörgWMittag Glad you know of Intentional, and hence perhaps why I react strongly to the "we're not using stone knives and bearskins" rationale. :-) Though I say source is source; if a text editor doesn't version and transact the underlying structure, it's not the source. While I'm text-averse, for the sake of exploring what can be accomplished with carefully controlled anti-complexity methods...I have become intrigued with Rebol and Red and am trying to help with them. Commented Apr 22, 2014 at 3:19
3

I going to go further than "Yes, they should be in" and say they're a basic requirement for any modern language and something I would just expect to work, at least 2 levels, preferably // and /* */ since that's what most developers are used to.

While I agree with @Telastyn that:

Leaving commented code in your code base is an anti-best practice with the ubiquity of source control systems (and distributed systems make it even easier).

The IDE & language I use at work (Embarcadero Delphi) has 3 kinds of comments "//, { } and (* )", which can be nested: // in { } and { } in ( *).
Even CSS and HTML have multi-line comments!

It sounds as though in this case the designers aren't producing an IDE and editing will be done in a 3rd-party test editor.
In this case there's another important point, not all text editors are created equal, although most modern editors provide these kinds of facilities (not always with keyboard shortcuts), sometimes you may not have access to them or don't want to open a programmers editor to make a small tweak.

It all comes back to developer (as the customer in this case) productivity.

Multi-line comments can be hugely useful during development when trying things out, re-factoring or almost any other development task, especially when you need to change things in multiple places at once just to see if something works.

They can also be useful when adding comments to the top of a source code file, such as legal/copyright notices, dates of major/important changes (not a substitute for good commit comments) or anything else that may be useful to have prominently displayed at the top of the file for at-a-glance reference.

3
  • My proposal is actually a hybrid, in that I want the multi-line comment form to only be able to comment out well-formed code. I don't want it to become competitive as a textual comment form. So if FOO BAZ BAR isn't a valid language construct, then /* FOO BAZ BAR */ wouldn't be a valid multi-line comment. This would prevent there from being variations in standards over which form to use for general commenting; it could only be used to comment out parseable code, limiting its use to the appropriate cases and calling itself out as temporary and not often checked in... Commented Apr 22, 2014 at 9:28
  • 1
    @HostileFork - sorry, I guess I misunderstood the question, though commenting out valid code is extremely useful day-to-day, I personally see no reason to stop there since it would probably be more difficult to implement your more restrictive proposal. The easier a feature request is, the more it is to be implemented.
    – SteB
    Commented Apr 22, 2014 at 11:28
  • One could comment out a string constant still with /* {gibberish here} */ and it would still work. It would not be significantly more difficult to implement the proposal in a compiler. And program headers are done with structure in Rebol, for instance. My restriction was an idea to prevent competition with the existing single line comment formats, when the larger purpose is to be able to snip out bits of code temporarily. Commented Apr 22, 2014 at 23:50
1

With a good editor “multi-line” comments are not required at all. For example, in C you can have fifty lines of comments by starting each line with “//“. You can “comment out” 50 lines of code if your editor lets you select lines of code and preceded them with “//“ and turn them back into real code if the editor lets you select fifty lines starting with “//“ and remove the “//“ characters.

Something similar can be done in practically all languages. There are sometimes problems if you have a situation where some code is required; for example C after “case xx:” or shell scripts between if and fi.

Now some languages with multi-line comments allow nested comments, for example Swift. In Swift, most but not all code including comments can be turned into a multi-line comment by including it between /* and */. So multi line comments allow you to comment out long bits of code without editor support if you are a bit careful.

0

Multi-line comments are handy for disabling a piece of code. It can be temporary, for example to test how the system would run without a piece of code, or permanent, for example if you want to leave a piece of old code there along with comments why that old code was removed to prevent others from experimenting with a similar way of doing things in the future.

Of course, in some systems there can be alternatives. For example, C and C++ have a preprocessor that can be used to disable code with #if 0. The nice feature about #if 0 is that it nests unlike multi-line comments. But my opinion is that if you are going to have disabled code inside disabled code inside disabled code ... then you are leaving way too much old disabled code there, and should consider removing some of that. A valid concern however is that if you want to quickly disable a piece of code that already has at least one multi-line comment in the middle of it.

But for systems not having preprocessor to disable code, it's a very good feature that I can disable a large piece of code just by adding two markers, the start of comment and the end of comment.

If you are designing a new language without preprocessor, you could of course make comment start and end markers nest. For example,

this is not comment /* this is comment /* this is nested */ still comment */ not comment

That would be very handy if there's a need to disable temporarily a large block of code that already has multi-line comments in it.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.