2

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

  • 1
    relevant question stackoverflow.com/questions/397148/… – Rotem Apr 22 '14 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. – HostileFork Apr 22 '14 at 1:42
  • Curly braces as string delimiters? Does that mean it uses " for statement grouping? – Rotem Apr 22 '14 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...) – HostileFork Apr 22 '14 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 Apr 22 '14 at 2:30
10

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.
  • 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? – HostileFork Apr 22 '14 at 2:47
  • 4
    @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 Apr 22 '14 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. – HostileFork Apr 22 '14 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. – Jörg W Mittag Apr 22 '14 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. – HostileFork Apr 22 '14 at 3:19
2

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.

  • 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... – HostileFork Apr 22 '14 at 9:28
  • @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 Apr 22 '14 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. – HostileFork Apr 22 '14 at 23:50

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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