Should the syntax for disabling code differ from that of normal comments?

Question

For several reasons during development I sometimes comment out code. As I am chaotic and sometimes in a hurry, some of these make it to source control.

I also use comments to clarify blocks of code.

For instance:

MyClass MyFunction()
{
    (...)
    // return null; // TODO: dummy for now
    return obj;
}

Even though it "works" and alot of people do it this way, it annoys me that you cannot automatically distinguish commented-out code from "real" comments that clarify code:

• it adds noise when trying to read code
• you cannot search for commented-out code for for instance an on-commit hook in source control.

Some languages support multiple single-line comment styles - for instance in PHP you can either use // or # for a single-line comment - and developers can agree on using one of these for commented-out code:

# return null; // TODO: dummy for now
return obj;

Other languages - like C# which I am using today - have one style for single-line comments (right? I wish I was wrong). I have also seen examples of "commenting-out" code using compiler directives, which is great for large blocks of code, but a bit overkill for single lines as two new lines are required for the directive:

#if compile_commented_out
    return null; // TODO: dummy for now
#endif
return obj;

So as commenting-out code happens in every(?) language, shouldn't "disabled code" get its own syntax in language specifications? Are the pro's (separation of comments / disabled code, editors / source control acting on them) good enough and the cons ("shouldn't do commenting-out anyway", not a functional part of a language, potential IDE lag (thanks Thomas)) worth sacrificing?

Edit

I realise the example I used is silly; the dummy code could easily be removed as it is replaced by the actual code.

Answer 1

First of all, in your example there are "TODO" comments. These types of comments are special in a way because they are detected by IDEs (at least Eclipse and Visual Studio) as a marker for "tasks". But I'm sure you know that since you use thme, and I suppose you're not referring to them when you use the term "disabled code".

As for the disabled code itself, my opinion is that it pollutes the code. I use another mechanism to keep track of what was there before: the source repository. Except when I'm in a code/test/code/test... mode, I don't comment unused code, I remove it. And when it's the case commenting X lines is just a matter of one keyboard shortcut.

Edit: so yeah, I forgot to answer your explicit question, I think that it's not useful to have special comments for disabled code. If you really want to keep the code, but say "don't use it", you can always mark it as @deprecated but that was not the point of your question.

Answer 2

Even if there's only one comment syntax in the language you're using you can still add your own flavour onto it, I've worked on projects where // denoted a disabled line and //-- indicated a comment. It's not as nice as having it built in, but most IDEs don't know you've used the different syntaxes for different purposes, so sometimes the old way of eyeballing to see the difference works best.

Answer 3

For several reasons during development I sometimes comment out code. As I am chaotic and sometimes in a hurry, some of these make it to source control.

I think this is the root of the problem. Being chaotic and rushed is only going to introduce problems. Figuring out why your development is being rushed and isn't well controlled should be the first step, not trying to find commented out code.

So as commenting-out code happens in every(?) language, shouldn't "disabled code" get its own syntax in language specifications? Are the pro's (separation of comments / disabled code, editors / source control acting on them) good enough and the cons ("shouldn't do commenting-out anyway", not a functional part of a language) worth sacrificing?

I don't think so. Commented out code is a bad practice and I don't think languages should encourage anyone to use it. Yes, people do it and I've seen it, but I refuse to check in code of mine that is commented out. Giving people the ability to easily manage unused, old code is beyond the scope of a language and is something that belongs in the realm of version control.

I'm also concerned about technical limitations. In order for this to work, you would need to either parse comments and determine if they are commented out source or text or add a new token to the language. Depending on the current complexity of the language, I'm not entirely sure what impact this would have on compilation (identifying if a line is or is not valid code to be compiled). Also, people would then expect IDEs to manage this in real time (is there a relationship between complexity of a language's syntax and IDE responsiveness to finding and highlighting various constructs and errors).

Answer 4

In opposition to the answers, I'll answer with a "YES, there should be different syntax!"

I would challenge any developer to say that they go through even one day of coding without commenting out code. To do so does not mean one doesn't know source control or is lazy. Even as Thomas Owens says in his dissenting answer, "Except when I'm in a code/test/code/test... mode, I don't comment unused code."

How much of of your time is spent in code/test/code/test mode? For me that's at least 90% of work! At the moment I'm converting a large OSX project to iOS, and the first step was to disable all the code that was breaking until I had a stub that worked. For the next weeks I'll be slowly uncommenting and fixing code as I get it to work.

There are many other cases as well. What about when you're using example code where you often find directions like "Uncomment the following for Windows" or "Uncomment the this line for iPhone-only Apps"?

Yes, I'll be using source control all along. But also YES, I would love there to be a way to distinguish disabled code from actual comments.

In summary: Any programmer who says they don't use comments to disable code is lying. There is more to coding than the polished files you commit to HEAD. There are many valid reasons for disabled code.

Yes it would be nice if there were a syntax (or at least a convention) to distinguish true comments from disabled code.