Commenting out code

[andrewbaxter]

The basic issue is // is ambiguous to whether what follows is for humans (markdown) or commenting out code (literal). So I chose the human one, since the former needs automatic formatting (and this project's all about formatting things automatically) and the latter is I feel probably rarer and kind of a WIP hack thing so I thought it was less important.

One option is to treat /* as verbatim, but editors that have a hotkey for commenting blocks of code vary in whether they do // or /* which reduces the effectiveness, and it's not like people can't use /* for human comments either.

My current solution is I introduced a new //. verbatim comment style, but another solution would be good. At the very least adding /*. for consistency would probably be a good move.

This issue is about coming up with a full solution though.

[AaronKutch]

Interesting ideas. 99% of the time when I use /* it is for commenting out code or special text that I don't want formatted. Rustfmt doesn't do anything ever to /* and prints errors if /* comments exceed line length limits, which I feel is the best approach for them. One thing about commented out code in // is that it either has a lot of leading spaces for indentation or has a lot of trailing ;s.
What I do in VScode sometime is ctrl+/ which doubles up the // if I commented a comment.
e.x.

    // // comment
    // let mut file0 = std::fs::OpenOptions::new()
    //     .truncate(true)
    //     .write(true)
    //     .create(true);

[rootnas]

After using genemichaels for a while now, I have acquired a feel for what I like about formatting code and what I think genemichaels does best: it makes editing code easier. Given this, I personally think formatted comments should be opt-in, ie //. this gets formatted as markdown, and the default behavior to assume comments are not to be formatted. This is because, while I may have more docu-comments in my code than I do code disabling, I disable code more often than I write docu-comments and in a more irregular style than if I were writing docu-comments.

Docu-comments already entail writing in a special style, and typically one doesn't write a docu-comment then comment it out- they add newlines one at a time and type //. Adding a dot to this sequence doesn't incur much overhead in practice, but requiring a dot for disabling code comments can create a significant time penalty, especially if someone disabling some code forgets or doesn't know to add the dot.

Even remembering to add the dot, it has to then be manually removed when the code is enabled again, incurring a second time penalty and detracting from my personal workflow. Meanwhile, I will never "de-comment" a docu-comment.

I recommend pushing this overhead to docu-comments rather than code-disabling comments in order to enable a smoother workflow experience with genemichaels formatter.

[andrewbaxter]

I think that's a good point, that while /// and //! are explicitly for documentation, // is a bit less clear. And as @AaronKutch /* is probably mostly commenting out code too. I think it'd be reasonable to make not formatting non-doc comments an option, although I'd like it to be opt-out (format everything by default).

It's not entirely straightforward, there's a couple subtasks:

• Right now this formats by line. Block comments are converted into line comments to do this. So this would need additional logic for handling block comments and suspending the normal formatting flow. I think /* and */ could perhaps be treated as line elements (i.e. indented) and then the rest of the lines dumped as-is between them?
• Flag to control whether non-doc block comments are converted + formatted or not
• Flag to control how non-doc line comments are parsed/formatted

I'll make subissues for those. I'm not 100% sure how much time I'll have to work on them in the short term but I think they're reasonable requests and it won't make the codebase significantly more difficult to maintain.

[AaronKutch]

Remember that /* */ in Rust can be nested, it is horrible to work with in Java where they can't whenever you run into it.

[AaronKutch]

The convention I always use is that the first line of code in // comments has no space or more than one space in between the // and the code, while docs always have a single space. There is also the triple quote code block case where you want to apply this recursively to the code inside which can have /// //

A good stress test is with https://github.com/AaronKutch/awint which has almost every kind of commenting. There might be a few places where I'm not following my own rules but the vast majority should be representative.
e.x.

//! ```
//! // `InlAwi`s and `ExtAwi`s cannot have zero bitwidths, so zero width
//! // concatenations will cause their macros to panic at compile time or
//! // return `None`.
//! let r = 5;
//! assert!(extawi!(x[r..5]).is_none());
//! // error: determined statically that this concatenation has zero width
//! //let _ = extawi!(x[5..5]);
//! ```

[rootnas]

I think that's a good point, that while /// and //! are explicitly for documentation, // is a bit less clear. And as @AaronKutch /* is probably mostly commenting out code too. I think it'd be reasonable to make not formatting non-doc comments an option, although I'd like it to be opt-out (format everything by default).

It's not entirely straightforward, there's a couple subtasks:

• Right now this formats by line. Block comments are converted into line comments to do this. So this would need additional logic for handling block comments and suspending the normal formatting flow. I think /* and */ could perhaps be treated as line elements (i.e. indented) and then the rest of the lines dumped as-is between them?
• Flag to control whether non-doc block comments are converted + formatted or not
• Flag to control how non-doc line comments are parsed/formatted

I'll make subissues for those. I'm not 100% sure how much time I'll have to work on them in the short term but I think they're reasonable requests and it won't make the codebase significantly more difficult to maintain.

The main issue is that right now genemichaels treats //as documentation (though it is useful sometimes since /// can't be used in some places).

[rootnas]

although I'd like it to be opt-out (format everything by default)

I misread your entire comment earlier. Would this be a switch in the config? That's an acceptable compromise. Would it be too much to ask for "format prefixes" (ie only format comments with // for opt-in, and //. or `` for opt-out).

[andrewbaxter]

Oh yeah, sorry, I should have been more clear.

Re: prefixes, so you want to have formatted non-doc comments but just have the default be unformatted? I think that's reasonable. It should probably be something other than //. otherwise if you're used to //. doing something in one codebase and then move to another codebase with the switch flipped it could be confusing (or, more confusing than necessary).

I'll see if I can add the switch for that tomorrow, maybe release the fix for the macros at the same time.

[rootnas]

Oh yeah, sorry, I should have been more clear.

Re: prefixes, so you want to have formatted non-doc comments but just have the default be unformatted? I think that's reasonable. It should probably be something other than //. otherwise if you're used to //. doing something in one codebase and then move to another codebase with the switch flipped it could be confusing (or, more confusing than necessary).

I'll see if I can add the switch for that tomorrow, maybe release the fix for the macros at the same time.

That sounds amazing! And if you don't want to leave it up to the user, might I recommend //? my clarifying comment as the prefix?

[rootnas]

Not the whole thing, just the //? part

[andrewbaxter]

Okay have an mr for #103 (should be linked there), 104 will be a bit harder although I have an idea how it could be done now.