Allow nested block-comments

[am11]

Extend block-comments to support nested block-comments to reduce code change noise.

Consider this code (click to exapand)

        public bool IsDigit(int offset = 0)
        {
            var character = buffer.Peek(offset);
            return character >= '0' && character <= '9';
        }
/*
        public int AsDigit(int offset = 0)
        {
            return buffer.Peek(offset) - '0';
        }
*/
        public bool IsHex(int offset)
        {
            var character = buffer.Peek(offset);
            return
                (character >= '0' && character <= '9') ||
                (character >= 'A' && character <= 'F') ||
                (character >= 'a' && character <= 'f');
        }

To additionally comment out other two methods, the recommended way is to use single-line comments // for each line, which produces this kind of noisy delta:

really noisy diff

-        public bool IsDigit(int offset = 0)
-        {
-            var character = buffer.Peek(offset);
-            return character >= '0' && character <= '9';
-        }
-/*
-        public int AsDigit(int offset = 0)
-        {
-            return buffer.Peek(offset) - '0';
-        }
-*/
-        public bool IsHex(int offset)
-        {
-            var character = buffer.Peek(offset);
-            return
-                (character >= '0' && character <= '9') ||
-                (character >= 'A' && character <= 'F') ||
-                (character >= 'a' && character <= 'f');
-        }
+//        public bool IsDigit(int offset = 0)
+//        {
+//            var character = buffer.Peek(offset);
+//            return character >= '0' && character <= '9';
+//        }
+///*
+//        public int AsDigit(int offset = 0)
+//        {
+//            return buffer.Peek(offset) - '0';
+//        }
+//*/
+//        public bool IsHex(int offset)
+//        {
+//            var character = buffer.Peek(offset);
+//            return
+//                (character >= '0' && character <= '9') ||
+//                (character >= 'A' && character <= 'F') ||
+//                (character >= 'a' && character <= 'f');
+//        }

The alternative approach is to start a new block comment after each comment-end that is on the way *//*. The differential in that case depends on number of intermediate block-comments and in this example looks like this:

less noisy diff

-
+/*
         public bool IsDigit(int offset = 0)
         {
             var character = buffer.Peek(offset);
             return character >= '0' && character <= '9';
         }
-/*
+*//*
         public int AsDigit(int offset = 0)
         {
             return buffer.Peek(offset) - '0';
         }
-*/
+*//*
         public bool IsHex(int offset)
         {
             var character = buffer.Peek(offset);
...
                 (character >= 'A' && character <= 'F') ||
                 (character >= 'a' && character <= 'f');
         }
-
+*/

If nested block-comments support is added to C#, like Kotlin and Swift, the example delta would only touch two lines:

desired diff

-
+/*
         public bool IsDigit(int offset = 0)
         {
             var character = buffer.Peek(offset);
...
                 (character >= 'A' && character <= 'F') ||
                 (character >= 'a' && character <= 'f');
         }
-
+*/

The compiler rule in case of both, Kotlin and Swift, is that the markers must be balanced. i.e.

/*
Example of nested comments
 /*
    using glob pattern: directory/*.tmp
 */
*/

is invalid; and by appending an additional */, it compiles successfully.

[HaloFour]

This would change the meaning of existing source as what is currently not a comment would become a comment, potentially in subtle ways that wouldn't necessarily result in a compilation error.

To be honest, I prefer the noisier diff. It makes it much clearer that the commit is removing an entire block of source. Otherwise it looks like you're only changing two lines, which while textually correct is not semantically correct. However, I much prefer to simply remove the lines and let my VCS manage the history.

[YairHalberstadt]

However, I much prefer to simply remove the lines and let my VCS manage the history.

Commented out code tends to make code harder to follow, doesn't stay semantically correct, and is almost never added back in at a later stage.

If you need to, add a comment referencing what the deleted code did, why it was deleted, and the commit Id where the code was deleted, and then just remove it entirely.

[CyrusNajmabadi]

is invalid

By definition, this would then be a breaking change. There would certainly be code negatively impacted by this.

If you wanted a nestable comment, it works likely have to use an entirely different syntax (for example, what f# does)

[MillKaDe]

Use preprocessor directives to comment code out:

#if false
void foo () { ... } // keep old version of foo() until the new version works
#else
void foo () { ... } // a newer version of foo() still under development
#endif

Blocks like that can be nested.

[The-Futurist]

@am11 - The C# designers never considered nestable comments as a requirement and adopted the messy grammar of C, C++ and Java as the basis for the syntax. As people have pointed out allowing /* --- */ to nest will therefore be a breaking change.

There are times during development when as part of experimenting or exploring certain ideas, it is helpful to be able to temporarily comment out a chunk of logic that itself may contain comments.

This is the main use case I have for this.

[CyrusNajmabadi]

There are times during development when as part of experimenting or exploring certain ideas, it is helpful to be able to temporarily comment out a chunk of logic that itself may contain comments.

This is pretty trivial in VS. Just select the area you want to "temporarily comment out" and do ctrl-k, ctrl-c.

I don't think a language feature is needed here when this sounds like just a tooling request for something that already exists.

[The-Futurist]

@CyrusNajmabadi - This is true, you're quite correct, so long as we're using tools that have that feature - I guess nobody edits .cs code in notepad these days!

[CyrusNajmabadi]

I guess nobody edits .cs code in notepad these days!

If they do, then this will be something they will have to deal with. The language is not, and is not ever likely to be, designed to make the life of a notepad user easier. There are a ton of good IDEs out there. There are also a ton of good text editors as well. All platforms are replete with them. If someone is avoiding all that, but wants the language to expend effort to still make their life nice in such a barebones tool as notepad, then they're expecting the wrong thing from this language.

They're welcome to use other languages though if those languages feel like the notepad-use-case is valuable to optimize for.

[YairHalberstadt]

@CyrusNajmabadi
Whilst editing code without an IDE is not recommended (which is what this issue is about), the language I think should still worry about viewing code without an IDE, since a lot of tooling (gitlab, GitHub etc.) doesn't have a good native way of showing semantic information. It should ideally not be required to have an IDE to understand what code does in the majority of situations.

Again, not necessarily a disagreement, since you were talking about editing, but perhaps a caveat.

[am11]

The focus of this issue is on reduction of delta, number of lines touched (by IDE or manual edit), when commenting out a portion of code file, be it the code block with block-comments or a block-comment containing /* and */ markers. The preprocessor directive workaround pointed by @MillKaDe provides such ability.