Question-Driven Commenting
I've always loved Titus Brown's notion of stupidity driven testing. It's okay to make a mistake but you write a test to make sure you don't do it again.
With Pinax, I've been adopting the sister practice of "question-driven commenting". When someone asks me what a function does or how to implement a particular extension, that's when I go and add comments to the code.
Of course, the person asking the question could be me :-)
Comments (7)
Kent on May 28, 2008:
I have long had a similar practice. Whenever I get a question from a user, I look at how I can change the program or the docs so that I won't have to answer the same question again.
Justin Pitts on May 29, 2008:
(Wow, the spam is bad.)
You could argue that code in need of comments is a sign of code that could be written more clearly.
James Tauber on May 29, 2008:
Got rid of spam:
delete from cms_comment where author_ipaddress='78.129.208.130';
I would sometimes agree with you Justin (see, for example my blog post Documentation Can Speed Up Your Code). But there are some things that easier to introduce with natural language than code.
The trick is knowing when and hence this notion of doing it in response to questions about the code.
You're right, though. The answer could sometimes be to just write the code more clearly.
Doug Napoleone on May 29, 2008:
Crap.
Looks like MATCHA has been broken >.<
Time for honeypot fields!
James Tauber on May 29, 2008:
I need to implement IP blacklisting in Leonardo.
I should also add a heuristic that if your name and your link field are identical, don't accept, as 100% of the spam that gets through the math question puts the same for both fields :-)
OpenID will come at some stage too.
Steve Holden on May 30, 2008:
Back in the days when, I would learn a codebase by commenting the code. It was always easier to leave it to someone else after that, since they had the learners' comments to read.
It's amazing how many assumptions we make in writing code that seem "obvious" to us but leave the reader with uncomfortable questions. The sad fact is that most people don't write code to be read, they write it to be executed.
Last Modified: May 28, 2008
Author: James Tauber
Brian Rosner on May 28, 2008:
I have always felt odd committing all whole bunch of comments. Now knowing its not as odd as I think, I have to felt this is a good practice :)