1

For a while now I've been in the habit of differentiating different kinds of comments in my code.

//this is an explanatory comment

//!this line was commented out for debug purposes, DO NOT SHIP WITH THIS COMMENT IN PLACE

//?this code was tested, and executed properly in 2.3 uS

This has saved me a lot of trouble, as I can quickly differentiate between debug comments and explanatory comments. It's especially nice to be sure that all my debug comments are gone, and none were accidentally left in place before publishing my code.

Is this a common practice? If so, is there a standard way of differentiating comments? Or are there perhaps better ways of achieving what I'm trying to achieve?

Improve this question
  • 2
    snarky answer: No, people use a revision control system like Git or SVN instead – amon Feb 21 '14 at 21:25
  • 4
    Each language has a different convention. From Pythons PEP 350 (which was rejected) to Java's TODO, FIXME, and XXX comments (which I am sure was in some sun document). That said, I've never seen your style before today. – user40980 Feb 21 '14 at 21:27
  • 1
    @MichaelT Java Coding Conventions -> 10.5.4 Special Comments: "Use XXX in a comment to flag something that is bogus but works. Use FIXME to flag something that is bogus and broken." – gnat Feb 21 '14 at 21:36
  • @amon: Do Git and SVN allow commit comments for every change in a file when the file's checked in? Our source control only allows a comment for the whole file itself - if there's multiple changes for multiple reasons, you have to put them all in a single comment for the check-in. I actually don't think this is such a terrible idea. – FrustratedWithFormsDesigner Feb 21 '14 at 22:07
  • 1
    @FrustratedWithFormsDesigner It's for a reason I explicitly marked my comment as snarky. However, it does have a serious background, here's the gist: “multiple changes for multiple reasons” – should be multiple commits. “This code was tested” – I do hope so. This could be enforced by commit hooks, or by the convention that stuff in a “stable” branch has always been properly tested. “Commented out for debug purposes” – just remove before committing (I have the habit of looking through the diff when preparing to committ a change). – amon Feb 21 '14 at 22:21
2

There basically isn't a need for a standard for such comments, because the standard is usually to remove them before you check in.

That being said, @amon's snarky comment is pretty much right. There's a lot of benefit to be gained by taking advantage of your source control to remove debug changes. Basically, you make sure to only make debug changes since your last commit, then you can undo them all with a single command. Or run a diff first if you're paranoid about what will be undone.

Git is especially easy to use with this model because local commits don't have to be shared and you can easily make an entire branch just for temporary debug changes, or use stashing, or the index. However, I do it at work with perforce by shelving my work in progress before making debug changes, then unshelving when I want the debug changes to go away. I think most modern version control systems have a concept of shelving.

The other benefit to using source control for debug changes is you aren't limited to finding commented out changes. Added lines, partially changed lines, and rearranged lines are all undone with one command. You just make the changes you need, without worrying about how you're going to find them later to undo them.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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