Tuesday, May 4, 2010

On "newly added" comments

I have just seen an enumeration modified. Some new items have been added there. The developer, probably taught to comment his code, added //newly added comments next to each new item. I guess he is very satisfied about the cleanness of his work.

I can imagine three possible scenarios.

First, no one will ever touch those comments. As a result, the items will remain //newly added for anyone reading the file, no matter the date.

Second, after some time, these comments will be deleted.

Third, and perhaps most in line with "comment your code" imperative, the developer will once change his comments to something like //not recently added and finally to //added ages ago.

What is the purpose of these comments? They are valid for some limited time. Then they just cause some confusion and/or maintenance burden.

If your code repository provides versioning, and our does indeed, anyone can reliably see what was changed in files. There is no need to manually list the changes anymore.