Idea: Add Comment Type for "Commented-out Code"

I find it's easy to forget to "uncomment" and/or delete "commented-out" code before committing it to git.

I wonder if we could add a new kind of comment that indicates to the compiler that code is being being switched off temporarily. The compiler would then warn you that you need to resolve the commented-out code at some point.

You'd need editor support to modify the default "commenting-out" command so that it uses this new type of comment.

Example

Situation

Say you're debugging, and you want to temporarily change the Default implementation of your custom pointer type to use a more grep-able address. You might write a temporary implementation and comment out the original like so:

struct CustomPtr {
    addr: usize
}

impl Default for CustomPtr  {
    fn default() -> Self {
        //⍝ CustomPtr {
        //⍝     addr: 0
        //⍝ }
        CustomPtr {
            addr: 0xDEADBEEF
        }
    }

Where is a stand-in for whatever sigil the community decides upon.

(Unnecessary context: is the symbol APL uses to begin an end-of-line comment. Ha ha. I don't think it's the best choice for the sigil though.)

The Compiler Warning

When compiled, this code would give a warning like this:

warning: commented-out code
  --> your_crate/src/main.rs:42:8
   |
42 |        //⍝ CustomPtr {
...|        ...
44 |        //⍝ }
   |        ^ help: don't forget to resolve/delete this commented-out code at some point!
   |
   = note: `#[warn(commented_out_code)]` on by default

Allow allow Attribute?

Should there be an attribute that one could put above the comment block which would ignore this warning? Something like #[allow(commented_out_code)]. I'm not sure why you'd want to do this though. The details of what this ought to mean would have to be formalized.

Editor Support

This idea would only really work if you could convince the major text-editors to change CTRL + / (or whatever shortcut comments-out code) from using //-comments to using these new //⍝-comments, but that doesn't seem impossible.

Conclusion

I know there have been lengthy (rather unfruitful) doc-comment discussions in the past, so I don't want to open old wounds. Just wanted to hear your thoughts.

1 Like

FWIW, in my day job (using C++ and Javascript) I intentionally comment out code as //foo because this triggers linter errors that it should be // foo in case I forget to do something with it. Works in both languages! :laughing:

I'm not sure how I feel about this proposal except that I'm very skeptical adding any Rust-specific syntax is the way to go.

9 Likes

I don't think this is a problem that Rust should try to solve. At my dayjob, we use DO NOT SUBMIT as a special string that if you add it to a comment, you will not be able to submit your code. I would encourage people to do something similar and incorporate a pre-commit hook (like this or this) into their workflow rather than add this to Rust.

5 Likes

Yeah that makes sense. This would probably make a better IDE plugin, since your IDE also knows about your version control software.

1 Like

I thought that's what /* … */ comments are for.

1 Like

I like IntelliJ’s approach here: for commented out code, it places // at the first column, without indentation. It makes it pretty easy to distinguish commented out and usual code, and also avoids splitting the comment block over blank lines.

8 Likes

The problem is that if I'm commenting out something, I do it as a "quick" thing to test something, or out of laziness. I wouldn't be adding any extra indicator.

Ideally, clippy should warn automatically whenever it detects commented-out code.

3 Likes

Yeah, so that's why the idea doesn't make sense unless you incorporate it into your editor's CTRL + / command. If you have to manually type this extra symbol, it's more clunky than it's worth. :laughing: But I think enough people use the editor command often enough that the idea has value.

I kinda like the idea of a clippy lint, but I'm steering more toward's @mjbshaw's idea of just making an editor plugin + a tool that runs in a git pre-commit hook.

That seems like a good way to do it! The point of this proposal would be to formalize that convention (at least within the context of an IDE or IDE-plugin) so that an automated tool could warn you before you commit your code to VCS.

Eclipse and Qt Creator also does it like that.

I do sometimes comment out code for quick tests. However, I wish that rather than commenting out code, I could easily cfg it out instead. More often than not, though, the code I want to comment out isn't a single item, so I can't just put a single #[cfg(FALSE)] around it. (And also, #[cfg(FALSE)] is awkward to type.)

I occasionally wish that it were as easy to wrap conditional compilation around arbitrary Rust code as it is to wrap #if 0 ... #endif around arbitrary C code.

You could use macros

macro_rules!disable{($($t:tt)*)=>()}

pub fn some() {}
pub fn code() {}
disable!{
pub fn and() {}
pub fn some_() {}
pub fn more() {}
}
pub fn etc() {}

Although something with proper syntax highlighting would be nicer.

Maybe a macro like this in std (better even in the prelude) is all we need so that tools can update their syntax highlighting properly.

1 Like

This changed recently. IntelliJ-Rust now puts the comment start in the column rustfmt would move it to.

1 Like

You can't use a macro to comment out stuff with unbalanced parentheses/quotes (the input must be valid rust token trees), while it's fine with comments and #if 0.

2 Likes

Yes, something that is independent of balanced parenthesis. Also, something that I can turn on and off from a single point

If you want to turn it on and off it ought to contain valid code. Why would you need unbalanced parentheses then?

In C, I sometimes want to do something like: a = fn ( #if 1 arg1, arg2); #else 1); #endif Where one of these is what was originally there. By doing things this way, I can more reliably remove the debugging code. I probably use unbalanced braces than parenthesis, but I think the name issue exists there.

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.