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.
Excellent! The less comments the better and the comments that do exists a tool could pick up and show me.
ReplyDeleteLast week I found a nonsense comment attached to a piece of code that only made me confused for while before I deleted the comment. This re-confirmed my belief why code comments suck and I realized one reason why:
Refactoring tools do not pick up comments and refactor them. Also when I manually search for all references and perform changes manually I usually only focus on a couple of lines of code and often miss the comments.
Jan: Glad you like it. I'm not too sure of the BECAUSE tag. Perhaps it should be replaced with a method and a method comment instead.
ReplyDelete