PPL: Day 6 - Bad comments

Legacy Post!
I've flagged this post as it is either, 1) No longer relevant/useful, or 2) Doesn't reflect my current thinking. Rather than delete these outdated posts, I've left them up so that search engine links remain intact and as a history of previous perspectives.

This is part of the Peer Pressure Learning 30 series. Jump to my introduction to the experiment if you got here from Google or some other site.

This is my first weekend PPL day and it almost broke me! It’s been a heavy week, so I was barely able to fall out of bed. Even then, it was 30 minutes later than usual and the kids were already going full steam. So here I am at 10:53pm because I really care a ton about this stuff. Thank goodness I got a Kindle copy of Clean Code as the paper one is collecting dust on my desk this weekend.

As a brief aside, I got a ton out of Gary V’s talk from RailsConf. I listened to it three times today. His push to make sure you do what really means something to you resonates a ton with me. Go watch it!

Enough rambling!

Today’s reading: pg 59 - 74

The section shares a rather long list of bad comment habits and styles. I couldn’t begin to do them justice. My thought is to share a few of the mistakes I’ve found myself making of late. Having jumped into my first group project (I never coded on anything with more than one full-time developer), I quickly got accustomed to writing comments. I didn’t do it at first, but our team lead quickly pointed out the damage that my sparse commenting would eventually cause. Now, about 6 months in, I think I’ve gone too far. I’m finding that I include header blocks on almost every method, no matter how obvious it’s purpose:

[Unfortunately the code I had shared to http://pastie.org/1012008 has been lost to Internet decay]

The worst thing I do (and I find that I do it in conversation, emails, and IM) is getting crazy wordy in comments. I’m so enthusiastic to explain what’s going on, why we implemented things the way we did, etc. that I’ve written small novels is a couple sections of code. Worst of all, they’re so long that it would be difficult to tech edit them later to make sure it’s all still accurate! Arg!

My goal for this week will be to cut the redundant/obvious comments. I’ll also look to use shorter, simple language when describing concepts. And when I find something that’s sufficiently complex to seemingly require a short book…I’ll see what can be done to simplify things. Wish me luck!

Take a moment (or save it into Instapaper…the most wonderful too ever) to read Miles’ Day 5 post on Scala

Published June 19, 2010

other posts »