Comment Re:Everybody Hates Documentation (Score 3, Insightful) 19
It remains worth the effort to write a novel around your code - not just what you did and why you did certain things a certain way, but the meta-reasons
I don't know if I'd go full novel, but I try to write my code so intention and implementation is clear with commentary to fill in the gaps. The farther things stray from that and/or the weirder the code gets, the more documentation I leave, especially if, for some reason, it needs to be like that.
While I enjoy the old saying, "Real programmers don't document 'cause if it was hard to write, it should be hard to understand.", I don't follow the practice; the harder it is to write the more documentation it needs. I also try very hard to be consistent in my implementations, style and commentary and have had several co-workers say they can tell it's my code just by looking at it. I learned that over time, mainly because I looked at my own earlier code at some point to reuse it and had trouble figuring out what I had done and why. I thought "Not cool, me."
So, I don't mind documentation, but will say that management is often loathe to allocate enough time for it to be done/maintained well.