In my lit­tle rant about crappy code com­ments — which was very light-hearted really, although it can be a seri­ous topic — Jay Greer com­mented and told me I should go out on a limb and post what I think are good com­ments. So here I go!

Sean Cor­field went through some of his own code and was sur­prised to find he’d left very few com­ments — and I would say that’s prob­a­bly because good code writ­ten with a frame­work rarely needs com­ments.

Here­sey, you say! But it’s true: it’s no secret I’m a big fan of Fuse­box. Some­one with big brains who knows lots about Fuse­box said — and as I’m not 100% sure who it was I’ll avoid mis-attributing the quote by not attribut­ing it at all — “don’t doc­u­ment your code, code your doc­u­men­ta­tion”. Fuse­docs or other forms of pre-documented code, in con­junc­tion with a frame­work like Fuse­box which is highly human read­able and has a log­i­cal, pre­set flow con­trol mech­a­nism, makes traditional-style code com­ment­ing largely obsolete.

That’s not to say that code com­ments are always use­less. The exam­ple com­ment that Sean put in his post is great — it clar­i­fies what a piece of non-obvious code is actu­ally doing. Those kind of com­ments are impor­tant for your own sake six months down the track as well as for other devel­op­ers’ benefit.

So enough preach­ing, what about me? While I’ve just come out and said that Fuse­docs are great, that doesn’t mean I always use them. Hell, I’d say mostly I don’t, espe­cially in the last year or so when all the code I’ve writ­ten has been really hec­tic with insane dead­lines. But my team finds that even our old code is very easy to revisit because it is Fuse­box (admit­tedly FB3), it fol­lows a set flow, every fuse­ac­tion is descrip­tively named, and every fuse is atomic. When a sin­gle fuse is called “dsp_listItems” and it only con­tains 30 lines of code, it’s not hard to work out what’s going on in it.

And where clar­i­fi­ca­tion is needed, like Michael White urges in his com­ment on the orig­i­nal post, maybe con­sider leav­ing a philo­soph­i­cal mes­sage for the poor sap left to main­tain your appli­ca­tion. Spread the love…