Code Comments

I am a firm believer of Programming by Intent and TDD as a means to communicate effectively with my fellow programmers (current and future). I find that sometimes this is not enough and I have therefore started using the following code comments to improve the communication.

TODO: why, why not

The TODO signals that here is incomplete functionality here. The comment should be followed by a reason why this should be done and why it isn't.

WTF: who doesn't get it, what

A WTF signals that there is something I don't understand. It is a signal to whomever wrote the code to clarify its intent by refactoring or with a BECAUSE comment. Hopefully this code is written by someone else. :) The WTF should be followed by my signature and what I don't get.

BECAUSE: who, why

A BECAUSE signals that I am unable to express my intent in code and that I need help clarifying it. The comment contains my signature and what I am trying to express. Hopefully I or someone else will be able to clarify my intent later.

REF: link

A REF signals that this code is described elsewhere. The code may be an algorithm that is described somewhere on the web or in a book. The ref is followed by a URL or some other pointer that allows whomever is interested to find the information easily. I usually add the comment patterns as to-do regexps in my editor making it easy to navigate to them. I also let the continuous integration server parse for them to give me a list of things that needs attention.

The comments also provide the additional value of showing the quality of the code.