Software Engineering Stack Exchange is a question and answer site for professionals, academics, and students working within the systems development life cycle. It only takes a minute to sign up.
Sign up to join this community
Throughout the course of programming, you will end up with some comments that explain code and some comments that are removing code:
// A concise description
const a = Boolean(obj);
//b = false;
Is there a good method to quickly parse which is which?
I've played around with using 3 /'s and /** */ for descriptive comments.
I've also used a VSCode plugin to highlight //TODO: and //FIXME:
There is a very simple solution to this: remove the commented-out code.
Really, there are only two good reasons to comment out code: to test something/make a fix, or to save code you might use later. If you're testing or fixing something, remove the commented out code as soon as you're done with the test or fix. If you're saving code you might use later, make it first-class code and put it somewhere such as a library where it can be put to good use.
Adding to @RobertHarvey's excellent answer I believe there is only one legitimate reason I've ever encountered for saving commented code to source control, even temporarily: in case of non-obvious replacement code which should not or cannot be used right now for some reason. Even then most of the comment should be the explanation, not the replacement code. This could be a bug or a feature of the language which is not yet considered stable. It might look something like this:
# TODO: Replace with `foo = frobnicate(bar)` once <link.to/bug> is fixed
foo = [some complex workaround]
In this case, the work has already been done, but you can't yet take advantage of it, so deleting it means someone would have to rediscover it later. The same goes for suboptimal solutions which may seem superior on the face of it or conscious trade-offs against similar solutions.
Caution: Don't litter your code with alternative solutions. Every task can be done in infinitely many different ways, and it's not cost-effective to explore this space for a long time for every change. Code reviews can be a good place to discover such missing comments, when your colleague suggests an improvement which you have already discovered to be suboptimal.
frobnicate(bar), so that no one will come along and try to "fix" your "inelegant" code. So you show them that you know that in a perfect world, the frobnicate function would be the way to go, but you know from painful experience it doesn't work correctly. There may be no expectation whatsoever that the third party even considers it a bug, much less worth fixing; you still need to leave a comment to future programmers (including yourself) about why you didn't take the obvious approach.
Jul 8, 2019 at 17:57
Hmm, I read this question slightly differently from Robert who correctly asserts that commented out code should be removed.
If, however, you are looking for a convention to mark code for later removal, an old favorite of mine is:
//b = false; //TODO: remove
Some IDE's flag //TODO: comments or can be taught to. If not, it's usually a searchable string. It's best to follow whatever convention your shop has established because this can be done several ways. Every code base should do this one way. Keeps it searchable.
quickly parse which is which?
Without that mark the automated way to do this is with the compiler. If stripping the comment off produces code that compiles, it must have been commented code. Writing an IDE plugin that checks that wouldn't be hard. But it will leave buggy commented code behind.
This is why it's better to simply mark commented out code as code the moment you comment it out. This lets you work non-destructively while you decide if you really want it gone. Since we all get interrupted, and are somewhat forgetful, don't be surprised if some lines get checked in while in that state. If they do it's nice that they're at least clearly marked and searchable. Keyboard macros have helped me with this in the past. It's hard to get interrupted in the middle of this if you can do it with a single keystroke.
You can take this as far as enshrining the mark in your continuous integration tests. Oops, I'm trying to check in with outstanding TODO's again.
double buffer (flip on) -> C prototype or ultra-terse English? can't tell without context, not a correct whole construct in either language. Some false positives and negatives are inevitable, when comments by their nature don't constrain the form of their content in either direction.
Jul 7, 2019 at 10:06
I use preprocessor directives to remove code, not comments at all:
//comment
active_code();
#if FALSE
inactive_code();
#endif
This makes a very easy thing to search for, and my syntax highlighter treats it as a comment. I can even collapse it into a single line: #if FALSE(...)
You can expand on that idea to have several options:
#if OPTION == 0
code_for_option_0();
#elif OPTION == 1
code_for_option_1();
#else
code_for_all_other_options();
#endif
And compile-time error-checking:
#if FOO >= 5
#error FOO should be less than 5!
#endif
Of course, you don't want to go overboard on this, or it becomes difficult to tell what's actually getting compiled and what isn't. But you get the idea, and it's the same problem as for commented code anyway...as long as you only use it statically. If your conditions are dynamic, it's worse.
To determine which is which in an existing codebase that didn't consider this problem at all, I don't think there is a universal solution. You'll have to find patterns yourself and probably code a regex to find them.
javascript. You could do some pre-processing but it's going to stretch the build system's capabilities and it's also non-standard. If you don't have a build system or the build system doesn't at all support parsing and executing code, you will not be able to implement this solution. Finally, it doesn't even address the question - commented out code is not strictly equivalent to code that is conditionally activated. It could be a leftover that's not meant to be enabled.
I agree with the answer stating that old code should be removed rather than commented out where possible, however I have observed a convention for those few occasions when commented-out code is needed.
(My basis is C# but this can be applied to any C-syntax language eg java)
// An explanatory comment has a space between the comment marker and the content.
// The following lines are commented out code so do not have the space (except where indented).
//var a = something();
//if(a==2) {
// doSomethingElse();
//}
// to the first column, and since virtually all code is indented, the result is virtually always that the comment starts with some tabs. Normal comments don't get a leading space from me, unless there are already other comments with a leading space in the vicinity. So, your method would fail abysmally on comments that I produced, and any method designed to recognize my comment patterns would fail abysmally on yours.
Jul 6, 2019 at 17:01
I am interpreting the question different still, thinking you want to find commented out code.
C-style code is bound to have semi-colons in it while comment is unlikely to have semi-colons in it. So for single line commented-out code you could use this regular expression:
\s*\/\/[\s\S]*;
For multi-line commented-out code it could be
\/\*[^\;]*;[^\;]*\*\/
Note Visual Studio is a bit peculiar about line breaks in regular expressions, they do not count as whitespace, you need to specify an explicit \n.
^\s*//.*;\s*$ as proposed in The Blog of Colin Mackay to work very well. Also, doing a commit before deleting code helps avoiding commenting it out.
Jan 17 at 14:02
If you use an editor with a compiler running in the background (like Xcode and Clang), you can just try to compile the text of the comment. For example”a concise description” gives errors, “b = false;” doesn’t. You could then use different syntax highlighting.
A simpler method would be an IDE plugin that uses some heuristics, like multiple words in a row other than keywords points to comments, matched curly braced point to code etc.
Other answers have covered variations on the "don't comment out code" theme. But sometimes you do still want it around for reference.
If you genuinely need the code to stay around, a better solution is to surround the code with "#if 0 ... #endif", ideally with a comment to say why. This is the recommended strategy from various coding standards, including MISRA.
Simple, at least for me - and in C/C++. Comments enclosed in /* */ are informative. Test code that is temporarily removed is commented out with leading //.
And there is good reason to leave test code in the file but commented out, at least in the sort of work I do. Sooner or later someone will want a change made, which will need that code. Uncommenting a block takes one editor command, as does re-commenting it where you're finished.
#ifdef __DEBUG ... #endif, or whatever custom definition you want to use. __DEBUG is nice though, because you often only have to change the project configuration to get it. But most IDE's let you define your own configurations as well, which can give you anything in that spot.
printf / cout or similar for getting newly-written code right (which I'll admit I have done myself in the past), it's really not very effective to leave them there. If somebody want to make changes and knows which variables they need info about, it's quick and easy to write the printfs anew, whereas if that dev doesn't know what's needed and just un-comments all those printf statements then the huge swath of text in the terminal likely won't help them either.
Jul 8, 2019 at 20:10
///and/** ... */comments are also used by some documentation generators, such as Doxygen or JSDoc. If you use them or similar tools, you may not be able to use that kind of comment for descriptive comments that aren't intended to be part of the documentation.