I disagree. You don't need to comment simple and universal concepts like this: swap :: (a, b) -> (b, a) swap (x, y) = (y, x) or even this: map ::

I disagree. You don't need to comment simple and universal concepts like this: swap :: (a, b) -> (b, a) swap (x, y) = (y, x) or even this: map :: (a -> b) -> [a] -> [b] map f [] = [] map f (x:xs) = (f x):(map f xs) Those functions actually are self-documenting. Trying to explain them further is just going to clutter the page. On the other hand, at 10,000 lines of code, a lot of that being parochial business logic, I'm going to want high-level documentation of why all this code exists. My emotional impulse is going to be to throw out all this shit code (in the business world, all code is shit) so please tell me why that is a bad idea. (I know it is, and I'm not going to do it, but please tell me why I'm not going to do it.) I'm going to want an entry point. I can't count the number of days of life I've lost just looking for entry-points in gigantic enterprise codeballs. Like, what actually runs? Actually, 10,000-line single-programs should be rare-- Big Software is almost always a mistake, see here: http://michaelochurch.wordpress.com/2012/04/13/java-shop-politics/-- http://michaelochurch.wordpress.com/2012/04/13/java-shop-pol... but that's another rant.