About David Green

David Green is a developer and aspiring software craftsman. He has been programming for 20 years but only getting paid to do it for the last 10; in that time he has worked for a variety of companies from small start-ups to global enterprises.

Are comments always wrong?

A colleague asked me recently:

Why aren’t developers writing comments any more?

He’d been looking through some code his team had written, and couldn’t understand it – he was looking for comments to make sense of the mess, but there were none. Before he challenged the team, he asked my opinion: should developers be writing comments?

Excessive Comments

When I started programming some years ago, I would comment everything, and I mean everything.

    // Add four to x
    x += 4;

My logic at the time was that it was impossible to tell the difference between uncommented clear code and gnarly code you just hadn’t spotted the gnarliness in yet. So I would comment everything, where the absence of a comment meant I’d forgotten – not that it was so trivial as to not warrant mentioning.

No Comments

Eventually I started working with peers who knocked some sense into me, and I immediately halved the number of lines of code I produced. At first it was a shock, but soon I realised that clear code is easier to read if there’s just less noise. And this is all (most) comments become: noise. Sometimes they’re accurate, sometimes they’re not. But you can’t rely on them, you always have to assume they might be wrong. So if the code and the comment seem at odds, you assume it’s the comment that’s wrong and not your understanding of the code (naturally you’re infallible!)

Clean Code

Uncle Bob and the notion of clean code have taken “no comments” to an almost fanatical zeal. But every time I get into an argument with someone about how maybe this time a comment might be justified: Ctrl-Alt-M, enter your comment as the method name and it makes the code more obvious. Every. Damned. Time.

However, the trouble with a zealous argument like this is it gets taken up by asshats and lazy people. It’s too easy to say “if you’d read Clean Coder you’d know you don’t need comments. Quit living in the past, grandpa!”. Uh huh. But your code is still a muddled pile of indecipherable crap. At least with comments there’d be some signposts while I wade through your steaming mess.

Some Comments

The truth is: sometimes comments do help (squeal clean code weenies, squeal!) There are some cases where extracting a method name isn’t sufficient. Sometimes having 20 one line methods in my class does not make it easier to read. The end goal is to produce understandable code. Generally, naming things properly helps. Adding comments that get stale does not. But that doesn’t mean that writing crap code and not commenting is the answer. Don’t use “no comments” as an excuse to leave your code indecipherable by human beings.

For example, sometimes you need to document why you didn’t do something. Maybe there’s a standard way of converting between currencies in your application – which this one time you’ve deliberately not used. A comment here might help future people not refactor away your deliberate choice (even better is baking your decision into a design – some class structure that makes it really obvious). Sometimes a method name really doesn’t do a line of code justice, it’s better to be seen in the context of the lines before and after it – but it really needs some explanation of what you’re doing. This is particularly true when dealing with complex algorithms or mathematical formulae.

Getting the Balance Right

How do you get the balance right? Well, your goal is to make code that other people can understand. The best way to get feedback on that is to ask someone. Either have explicit code reviews or pair program. If another human being has read your code and they could understand it – there’s a better than average chance that most other capable people will be able to read it too.
 

Reference: Are comments always wrong? from our JCG partner David Green at the Actively Lazy blog.
Related Whitepaper:

Software Architecture

This guide will introduce you to the world of Software Architecture!

This 162 page guide will cover topics within the field of software architecture including: software architecture as a solution balancing the concerns of different stakeholders, quality assurance, methods to describe and evaluate architectures, the influence of architecture on reuse, and the life cycle of a system and its architecture. This guide concludes with a comparison between the professions of software architect and software engineer.

Get it Now!  

Leave a Reply


+ five = 13



Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use | Privacy Policy
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.

Sign up for our Newsletter

20,709 insiders are already enjoying weekly updates and complimentary whitepapers! Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

As an extra bonus, by joining you will get our brand new e-books, published by Java Code Geeks and their JCG partners for your reading pleasure! Enter your info and stay on top of things,

  • Fresh trends
  • Cases and examples
  • Research and insights
  • Two complimentary e-books