Popular
Recently Written
Visitors
Archives
Apr
9
Commented Code Doesn’t Equal Clear Code
Filed Under Programming
There is a new round of discussion on the old comment your code or not chestnut:
Design for readability.
Even if you don’t intend anybody else to read your code, there’s still a very good chance that somebody will have to stare at your code and figure out what it does: That person is probably going to be you, twelve months from now.
Sure. Who wouldn’t agree with that?
But then the discussion goes a bit off the rails. I notice that Windows programmers love, love, love their IDE’s. I just don’t see how code completion can possibly be a significant productivity enhancer.
Programming is about thinking and communicating in code. It’s not about who can auto-complete obscure function calls the fastest.
Programmers ask me, “Shouldn’t I comment my code so that someone else can understand it?” My response to that is, “Why are you writing code that is hard to understand?”
I know that sounds jerk-off sarcastic, but really, I’m not trying to be. I’m seriously asking. Listen, writing good, clear comments takes time. It’s a non-trivial task. Given that, why not spend said time making the code clearer and more self-explanatory?
If a method does three different things with the middle thing being something obscure and hard to understand why not split that method into three methods each with a super clear and verbose name. Then when I read those methods called in sequence it will read like a story:
NowDoThisTrickThingThatIsObscure();
NowDoSpecificallyThis();
Via Out of Cheese and Daring Fireball.
In theory this sounds good, but in practice it’s a little more complicated. Even simple code can be hard to understand if you’re not familiar with the patterns being used. I find the level of documentation and required code clarity also depends on the context the code is being written. If I need to optimize an algorithm for performance, I’ll sometime sacrifice code clarity for a little extra speed, and carefully comment that code. Depending on the context, the trade-off is often worth it.
With respect to the IDE thing, I used an IDE heavily when working in Java and it was wonderful. Not because it did auto-completion, but because I had the entire code base cross referenced directly in my editing environment. The code completion was just a minor improvement that I could easily do without.
Yes correct, even clearly commented code could be hard to use sometimes. It takes a while to get used to the naming conventions and the little nitty gritties followed by the earlier software programmers. But It is always better to stick to the normal programming conventions though.
[…] discussing technology primarily. It is not the usual dry commentary. He has articles such as Commented Code Doesn’t Equal Clear Code and “Thinking Messy Monitors”. The latter reminded me of my own blog post - Increase […]