10 ms·

Literate programming - why have terse comments when you can have a verbose and rambling narrative? I actually tried reading the TeX source code, and it was damn

• ajross 14y ago
  I mostly agree. For 95% of code, it's simply a waste of time to try to "document" it like this. For the handful of situations where elaborate documentation wants to be stored with code (which basically means "automatic reference doc generation from API definitions") we have tools like Doxygen already that work well. But there does remain that tiny subset of code that is so complicated that it can only be explained in prose. This includes things like, say, DCT implementations, tight SIMD assembly, complicated threadsafety architectures, oddball parser context dependency rules, etc... I can see wanting to read this stuff in a "literate" environment. But... is anything you might use Coffeescript for going to contain code like that? I can't think of any good candidates offhand, beyond (perhaps) the coffeescript compiler itself...