The do’s and dont’s of in/out-commenting code

Commenting out code is used as means of modifying a system-block’s behavior with the option of rolling back the modification quite easily. This is convenient in many different scenarios, among which the following probably are the most common…

  1. You are debugging some code, and…
    1. you want to isolate some specific statements to see their isolated behavior.
    2. you want to replace a complicated line of code with a more simple variant, perhaps even involving hard coding some values instead of working with dynamic data.
  2. You are trying to sign off on an assignment, and someone else has broken the build by committing code to the configuration management system that breaks you build. Then you are tempted to comment out the lines of code that makes the compiler “bowl”.
  3. You are trying to leave some code statements inside the code to work as samples for ladder developers and perhaps even yourself later down the assembly-line.
  4. You need to remove some behavior for the current build, but the behavior of the code to be out commented is correct and valid and is very likely to be used down the assembly-line.

I can think of many more examples of situations where out commenting can be considered good practice… however, the consequences of out-commenting code should be made very clear to every person working with programming…

When leaving out commented code inside the codebase for other developers to follow up upon, the out commented parts needs to be described… the most important note to do in this context is to answer the question as of “why” this code segment was out commented.

Nearly every day I run into out commented code that is undocumented, and I am left with the alternative as of to remove it or to leave it and perhaps miss out on a thorough understanding of the code domain.

At least a couple of times a week, I actually discover bugs in systems where the bug is relating to some lines of code that has been out commented for some undocumented reason, and by being out commented resulting in undesired system behavior.

On my team, we have a practice to include tags or calls from a small selection as we see fit…

The classics are HACK, TODO, FIXME and then we have the wonder child of throwing a “new NotImplementedError()”…

…in conclusion, the solution is simple as how to remain out commenting code and still not doing significant harm to the quality and stability of systems… thus document your uncomments…

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s