Literate Programming Once Removed

So the Jeff's next chapter... Oh just go and read it yourself already.

As I mentioned in my last post the annoyance about Literate Programming is that you write a lot more and end up with the same amount of code (though it may be of a slightly higher quality). This old article puts forward a view very contrary view to the one I made in my last post by saying the comments are mostly just clutter. The funny thing is that until I tried this literate programming thing I would have probably just gone ahead and agreed with him.

I still do agree with basically everything he says. If you write in a language surely you should be able to read it too? If you can't then it is probably because the paragraphs, grammar and punctuation are all in the wrong places. The only thing I will say is that he brushes the times that comments are useful off quite lightly.

1. In the styles of Javadoc, RubyDoc, et cetera for documenting APIs others will use.

Yes it is most important that you document your API methods for external users but they are not the only users. If you write even a private method it is likely that people in your team are going to be using it before long. I would suggest that they would spend less time reading the intellisense than reading the method contents (or asking you how to use it).

4. Explaining why the most obvious code wasn't written. (Design decisions) 

I believe this one should include explaining why any of the code was written in the first place. The best code is already written, it does exactly what it should do, it's been tested and it does not need changing. When I read code I can usually tell exactly what it does at a glance. The hard thing to understand is why it does it. Sometimes there are business rules that are buried in a two year old spec somewhere, other times it is a severity 1 bug fix that never got documented and sometimes it is just a lack of thought when it was written.

When you write your reason for writing a piece of code you validate it's existence. Every bit of code is written for a reason and where better to document that than in the code itself. I think that is the thought that spawned literate programming and that is why I still think literate programming is still worth considering. Usually I find that the answer to this sort of issue lies somewhere in the middle of the two extremes.