But its more cool to see how concise I can make my code, not how readable and maintainable it is! 
Hmmā¦ Iāve use the Pseudocode Programming Process since before I read about it in Code Complete (Good book, Thanks Jeff!). And it generally works really well for me. I leave the Pseudocode in comments to tell future programmers what is going on. This process also helps keep the code and comments in sync because I even write the pseudocode for new features or changes to a function/procedure.
Iāve never really worked on a big programming team, generally there are no more than 3-7 programmers on the projects Iāve worked on. And a lot of times it was just me. I am an insecure programmer, so I comment just in case I did something that seemed brillinat to me, but is actually bad, bad, bad. That way if someone that is better comes along while I am still there and they see it, they can say, āHey, you know you can just do ā¦ā Then I learn and they get their ego fed.
But then again, I also code for readability over putting in the slick āI can write the entire function in 1 line C approachā.
My favorite comment Iāve come across while bug fixing someone elseās code - (* This entire function is commented out in case the b!tch changes her mindā¦ again! *)
ASDKLJAASKJ GRRRRRRrrrrrrrrRRRR
YOU KNOW WHO DIS IS? jbarthalomewe?
WHER I FIND?
G
asdkj
qweSDJJJJJJ!!!
The absolute worst crap Iāve seen is not just checking in code thatās logically wrong but also doesnāt even compile! In college if the code didnāt compile you got a zero but dang the folks in industry are supposed to be pros! Unbelievable! I try not to think of the craptastic code and all of the total rewrites that need to be done and then I can sleep well at night.
You canāt understand my code because itās so well written.
@KM You donāt write documentation and code like theyāre just a different form of representation of the same knowledge. DRY.
Write documentation for high-level knowledge, not low-level knowledge.
The Pragmatic Programmer book mentions this too: ā¦āThe comments will inevitably become out of date, and untrustworthy comments are worse than no comments at all.āā¦
Jeff that photo is pretty scary !!
Iām surprised no oneās pointed to a href="http://www.web-hits.org/txt/codingunmaintainable.html"How to Write Unmaintainable Code/a
Comments are fine, but maintainable code is so much more than just documentation.
Iāve had two sizable, heavily used codebases under my jurisdiciton, in my career so far. Lucky for me, the first was the very maintainable one. I learned a lot about the SDLC from that job.
Needless to say, the second codebase had several 1500 line sprocs that outputā¦ (wait for it)ā¦ html!
Also, I canāt believe no oneās mentioned Brian Kernighanās famous quote, āEveryone knows that debugging is twice as hard as writing a program in the first place. So if youāre as clever as you can be when you write it, how will you ever debug it?ā
@Tips: this is the funniest comment Iāve read here in a while:
āIām not really understanding your post or what itās aiming to!
I think you have to review some of the articles your are publishing hereā
Jeff, I certainly appreciate when you press the idea of best practices. However, letās all keep in mind that sometimes best practices have to take a hit from deadlines, stress, and bad management. Donāt be so quick to curse the developer of the code youāre struggling to maintain until youāve coded several thousand lines in his/her shoes.
Granted sometimes even under the most favorable of conditions people churn out bad code. But even the best and brightest might produce code thatās not up to their usual standard under certain circumstances.
Additionally, not everyone has really good peer mentorship. Some are learning as they code, developing best practices along the way (thatās certainly the story for me!) Code they produced even six months ago isnāt as pretty as the code they are producing today.
More blame is surely earned by the guy thatās been programming for years and still produces sloppy code.
Just keep an open mind.
My first job in college was doing tech support on a small commerial product. Being a small consulting firm, I was able to teach myself VB and work my way into development there. My first few assignments were maintenance work on existing client projects. Unfortunately, I learned more about how not to program and how painful unclear code can be to someone not familiar with it. To this day, I code with that pain in mind. As I code, I think about holding myself accountable to some imaginary maintenance programmer sitting next to me to whom Iām explaining the very code/comments Iāve just written.
That was priceless experience. Some of my coleagues have not had such experience and I can see it in the code they write; their whole approach to coding a solution.
In classic French kitchens, cooks didnāt go to school to attain their position, they worked their way up from dishwashing, to prep cooking (cutting vegetables, etc.), to cook, to chef. Along the way they learned every detail, both good and bad, of every aspect of a functional kitchen. That depth of knowledge and wisdom can only be gained through personal experience.
In school they always preached to write good code and comment your code so the next person could maintain it.
Of course, if you want job security, write your code so the next person canāt 
Acctually that doesnāt work so wellā¦ when you write something and then donāt look at it for a few months, you might as well be that next person. And then youāll be kicking yourself for coding that way.
Iāve never gotten angry because of code that I had to maintain but Iāve been profoundly saddened many times.
I believe being able to read code is as great if not greater skill than being able to write it. Having been a team lead, Iāve given legacy code that is still in production to programmers to be modified. Sometimes the programmer will come back after a cursory examination and declare the code to all be crap and that it needs to be re-written, even for code that was well written and had been peer reviewed. What I learned over time is that some programmers are really good at reading code and others are not.
I always do this for code Iāll maintain. Because itās true.
Jeff: Not entirely related to this post, but in the last two months, you had a post that discussed error handling on ASP.Net apps. (It might also have been on the stackoverflow blog.) You noted how it was the first thing you setup on a project, and it sounded like a neat tool.
I didnāt note that open-source project with a horrible name at the time, and Iāve been trying to find it - but I canāt find the post now, and canāt recall the name.
Am I going mad?
āAny of your code that you havenāt looked at for 6 or more months may as well have been written by someone elseā (canāt remember the name of the person who wrote it but its true in my experience)
And I agree with the sentiment that well written code should be fairly self-documenting. What I like to see in the comments is an explanation of any dependencies and business rules relating to WHY the code is implemented in that fashion. Your code tells me what you did, comments should explain the non-obvious.
You should make one of those motivational posters out of this image (with the bold text included of course). Thatās the best line Iāve read in a long long time!!!
Picture scared the crap out of me. Thatās all I have to say.