Archive for July, 2007

Comments on code comments

Friday, July 13th, 2007 Nigel Jones

People’s opinion on code commenting is a bit like their opinion on speeding (you know the adage – anyone that drives faster than you is a maniac, anyone that drives slower than you is a doddering old fool). With this in mind, I recently got into a bit of a disagreement with a faculty member of one of America’s finer engineering schools. Here’s a summary of our positions.

I’ve looked at this 750 SLOC file. It contains no header, no comments, or any other explanation as to what it does. The code itself is non-trivial, involving a large amount of recursion, dynamic memory allocation etc and thus what the code does and how it does it, and indeed why it exists is not obvious to me.

Based upon the file name it should be obvious what the code does. If you don’t understand the theory of this entity, then you have no business looking at the code. P.s. the code is documented