Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
    
I don't see anything too wrong with this - commenting out and uncommenting out small blocks of code is sometimes a useful tactic for debugging very specific bugs in large legacy code bases. I find this helps me narrow down problems (in addition to using a proper debugger, of course). I wouldn't mind seeing a special type of comment, maybe /# ... #/ that would highlight differently in the IDE (for visual cues) and maybe generate a compiler warning that would then be trapped and reported in by the nightly build if someone does check such changes back into source control. –  FrustratedWithFormsDesigner Aug 22 '11 at 14:54

4 Answers 4

up vote 18 down vote accepted

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.

share|improve this answer
5  
+1: That's what source control is for. –  DeadMG Aug 22 '11 at 11:18
    
I used to write dirty code and was proud of using "hacks" and quick fixes, nowadays I appreciate structure - perhaps I can get used to this as well. –  deltreme Aug 22 '11 at 11:32
2  
TLDR; Use source control. –  Chris Aug 22 '11 at 11:36
1  
@deltreme I admit that I was doing the same thing (show how I "improved" the code!) before I seriously started using a source repository in a professional environment. Since then, I appreciate having to read the fewest lines of codes I must every day. –  Jalayn Aug 22 '11 at 11:39
1  
Unfortunately the focus of the replies has been on how not to commit disabled code, not on how silly the term "commenting out" really is. I expected more of a mixture. Accepting this answer as I was asking for an opinion and you have the community backing you up :P –  deltreme Aug 22 '11 at 13:34

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

share|improve this answer
    
I am trying to manage my chaos and rush, and I agree totally that's where it all starts. However it currently happens and I'm sure that as soon as I am free from commenting-out code, someone else will take my place. Perhaps I'm just nagging. In the end it's not that big a deal. As for the technical aspects: IDEs could even treat them as regular comments, use a colour, or hide them - many IDEs already support this for other syntax elements. –  deltreme Aug 22 '11 at 12:26
    
@deltreme I don't care how IDEs would support them on the surface. How would IDEs find and process them in a manner is accurate yet maintains responsiveness? Adding tokens to a language or adding text processing has the potential to slow down parsing or yielding inaccurate results. –  Thomas Owens Aug 22 '11 at 12:27
    
I didn't think the discussion would go this way :) And I don't think adding another token (how many does a modern IDE recognise nowadays?) would result in a poorly responsive editor. If you see it as a potential threat even in the research stage of this "project", would you have an estimate in what the performance loss % would be? Say we add a token and want a colour for it in an IDE. –  deltreme Aug 22 '11 at 12:34
    
@deltreme I don't think it would add that much time for most projects, but in terms of time added/value added, the ratio is very poor. If you had to add that additional few microseconds to tens of thousands of source files, you just added milliseconds to everything that ever parses a source file, every time you parse a source file. For an IDE, that would usually be every time you save. It would also be to your post-commit and/or daily builds. Compound those milliseconds and it very quickly becomes measurable in minutes over a project's lifetime to deal with a feature that adds no value. –  Thomas Owens Aug 22 '11 at 12:38
1  
@deltreme Absolutely not. If you have disabled code in your project that's made it into source control, you're doing it wrong. Occassionally, if I'm rewriting a method, I might comment out the old method and reimplement it, but once I'm sure the new code passes tests and works as intended, I remove the disabled code and check it in. If you are actually checking in disabled code or relying on it in some way, that's a sign of larger problems in the project that need to be addressed. –  Thomas Owens Aug 22 '11 at 12:54

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.

share|improve this answer
    
If the team dedicates to this flavour it would certainly be a good workaround. It's even "on-commit-hook"-able, and if you forget the extra characters for something meant as comment, it would also alert. –  deltreme Aug 22 '11 at 11:38

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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