Constants instead of Comments


I often see the following in the code I'm reviewing. [sourcecode language="javascript"] ... // We have 15 default images var default_image_index = image_id % 15; ... [/sourcecode]

The line of code includes a numerical value and the preceding line is a comment describing the semantics of the numerical value. I think I'm on a crusade against comments, so I'm recommending my coworkers to write their code like this instead

[sourcecode language="javascript"] ... var NUMBER_OF_DEFAULT_IMAGES = 15; var default_image_index = image_id % NUMBER_OF_DEFAULT_IMAGES; ... [/sourcecode]

In this case, the name of the constant entirely replaces the need for the comment, with the added benefit that the constant is code while comment is not. This is a much more maintainable way to document your code and it makes searching for values used in your code much easier. Additionally, the moment you look at the code, you see which parameters can be tuned.