The best comment I ever read was huge, multi-paragraph monstrosity at the top of the file. It was written in a casual style and had misspellings. I think it gav

The best comment I ever read was huge, multi-paragraph monstrosity at the top of the file. It was written in a casual style and had misspellings. I think it gave an overview of the intent of the file (it was like some Perl script) and then rambled on about how the requirements had mopped him into a corner, and that the code was incomplete and likely buggy. It was shockingly humble and transparent, and yet it seemed to flow from confidence, someone who had lots of experience in systems of all shapes and sizes. It was not signed, but I'm pretty sure it was by one of three coworkers, each of whom had years and years of experience running servers and networks. Its tone was a refreshing contrast to slick smokescreen recited by your average drone, in meetings and emails in the surrounding corporation. And then there were no more comments. Yet the code was more comfortable to read, after that long intro, than most code I run into. I think it was two things: (1) The author stated the intent. What was the file's purpose in life? Every line is easier to take in after you know that. (2) The code was written by a human being, just like you and me. Usually code feels a little stiff, no doubt because the main audience member is a computer. A mild injection of warmth and humanity helps me keep my chin up when I face that daunting first read. Would it have been better if it was more concise, spelled perfectly, and had a few line-by-line comments? Maybe. But it was such a treat I still remember it a decade later.