Monday, 27 June 2011

Comments make your code alive. Otherwise, it's dead

[Image by W.Rebel]

I had a small discussion about code and comments with Bob MacNeal. Bob thinks that

Commented out code is the same as a comment - Litter. Don't litter.

I strongly disagree, although we had a nice conversation. It turned out that

@MartijnLinssen I'm an average coder at best, but I like clean code. I've made a living copying code from others. I dig good, clean shit.

That is the crux right there

I consider myself to be a good to great coder, doing complex stuff most if not all of the time. I also swap programming languages fairly often (I "speak" a dozen or so) and I hardly ever copy code from others. If I do so, I usually completely rewrite it to fit my way of coding, naming convention, error prevention and error handling - plenty of reasons to do so

And when doing so, I do add comments. A lot. I aim to have one line of comment for every 3 lines of code. That's not a law, but a rule to which exceptions are allowed

Why? Because writing code is not my goal. If your goal is to write code, like Bob, then you'll do that as quickly and efficiently as possible and get over it and away with it. It will be quick, relatively cheap, job well done.
But what if that code has bugs? Or needs new features? You'll have to dive into it again. That will probably a few weeks after, or even months, or years. Or it might not even be you - that chance is 99,999%

I learned to comment when I had to maintain code. Code written by others, but also written by myself. The very best way to learn to comment, really, is to have to maintain your own code. After a little while you'll wonder "Oh my, why am I doing that here? And what's that ++i doing - that should be an i++! And why on earth do I enter that catch there and do nothing?!"

So many questions, so little answers. So much time wasted to get those answers. There usually is functional and technical documentation, even detailed, sometimes even accurate and current - but those little programmer's smart moves are hard to figure out. Comments help a lot then, and save an awful amount of time and money.
In fact, the only time I wrote code (a complete application even) and didn't put in comments, that was on purpose and to prevent reuse and maintenance by others

The attitude I find here is the attitude I encounter ever more frequently in other areas as well. It's not only an inside-out view, it's more narrow. It's an attitude of OR, not AND. It's an après nous, le Déluge attitude that is contradictory to this world where everything is coming together again via internet, mobile and social media. No, I'm not going to mention the word Agile - rants enough about that

I don't deliver projects. I deliver products. Products that live on after the deadline of my project. So, I comment my code. And so should most everyone else

0 reacties:

Post a Comment

Thank you for sharing your thoughts! Copy your comment before signing in...