If it didn't take effort

I think every developer should be able to write his programs within a simple text editor. Knowing how to change your applications without your preferred IDE will be very valuable in precisely those situations where your IDE is not available. You know, at the live web server, at a customer site or even at the desk of another developer (if your organization chose not to standardize on one IDE).

But of course working within an IDE does make life much easier. Auto-complete is such a time saver (especially if it is the smart-complete type that IntelliJ IDEA introduced me to), and having parameter hints or even complete API help at your finger tips really makes a lit of difference.

But there is something I really don't like about the way IDEs try to save us time. They almost all have the ability to generate getters and setters for member fields. And when they do, they generate documentation for those getters and setters. That's great, because it saves you from having to write your own. Right? Wrong!

Since even the smartest IDE has no idea of the semantics of a certain getFoo method, all it can generate is documentation of the kind "gets the value of Foo". How useful is that? When was the last time you were using a certain API, weren't sure of the functionality of one of its getters, opened the API docs, read "gets the value of Bar" and thought "... of course, how silly of me not to realize that"?

Yet we all like it very much when our IDE generates such comments for getters we write (or actually generate). As it allows us to get to the finish as soon as possible. Let's see... the code seems to work, so what else is needed? Camel case all method names... check... Pascal cased the class name... check... Meaningful local variable names... check... And documentation for all public methods... we only have getters and setters, so that's a... check! We're done, so let's commit it and allow others to admire my work.

When I review someones code and see this type of documentation, I always make a note of it and pick it up with them. And to make it easy to remember, I've again come up with this one-liner: if it didn't take effort to write comments, they're of no value to me when I read them. My tech writer colleague's will probably nod in agreement when they read this, but it really is true. And don't you dare use this mentioning of tech writers to say that real documentation should really be in a separate written document, like a programmer's reference guide!

Think about it: how often do you look something up in the API docs of your language or library? How useful is that documentation? And how much effort do you think the creators put into it? Does it seem like half of it was generated by their IDEs? Or closer to the truth: if it looks like half of it was generated by an IDE, how often do you curse the developers for not providing you with better documentation? And more than likely those are precisely the libraries where you reach for the programmer's reference guide. Which was written by someone who really spent time on documenting the functionality, instead of hoping his word processor would auto-complete it for him.