In my little rant about crappy code comments – which was very light-hearted really, although it can be a serious topic – Jay Greer commented and told me I should go out on a limb and post what I think are good comments. So here I go!

Sean Corfield went through some of his own code and was surprised to find he’d left very few comments – and I would say that’s probably because good code written with a framework rarely needs comments.

Heresey, you say! But it’s true: it’s no secret I’m a big fan of Fusebox. Someone with big brains who knows lots about Fusebox said – and as I’m not 100% sure who it was I’ll avoid mis-attributing the quote by not attributing it at all – “don’t document your code, code your documentation”. Fusedocs or other forms of pre-documented code, in conjunction with a framework like Fusebox which is highly human readable and has a logical, preset flow control mechanism, makes traditional-style code commenting largely obsolete.

That’s not to say that code comments are always useless. The example comment that Sean put in his post is great – it clarifies what a piece of non-obvious code is actually doing. Those kind of comments are important for your own sake six months down the track as well as for other developers’ benefit.

So enough preaching, what about me? While I’ve just come out and said that Fusedocs are great, that doesn’t mean I always use them. Hell, I’d say mostly I don’t, especially in the last year or so when all the code I’ve written has been really hectic with insane deadlines. But my team finds that even our old code is very easy to revisit because it is Fusebox (admittedly FB3), it follows a set flow, every fuseaction is descriptively named, and every fuse is atomic. When a single fuse is called “dsp_listItems” and it only contains 30 lines of code, it’s not hard to work out what’s going on in it.

And where clarification is needed, like Michael White urges in his comment on the original post, maybe consider leaving a philosophical message for the poor sap left to maintain your application. Spread the love…