Wednesday, March 03, 2010

The default NetBeans IDE java source template is polluting the web

People will never bother to do anything manual unless absolutely necessary. This is why I believe the current NetBeans "empty" java file template is fundamentally broken.

It tries to "teach" people how to change the template by inserting in the file header something like:

/*
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */

This might sound like a great idea in practice but it's broken since most people won't change it. So it just becomes line-noise that will get published, committed to VCS, etc.

A good UI would display that message differently, like a floating non-modal dialog, or some notification in the New File Wizard, but it shouldn't produce actual text that is part of the source code file.

Google seems to say about the same: there are 321.000 instances of files indexed by the search engine containing that header. And this is only on the public web, I bet there are many more closed-source code repositories filled with these lines...

8 comments:

padreati said...

You are definitely right. I usually do a clean of this template after every fresh install or upgrade, but sometimes I forget.
My first problem with this header is that is not dependent on the project, or project group or similar. I think I could manage that from variables, but I did not search more on that. Just because I could have many projects, with different licenses or messages for headers and only one template.
You suggestion to throw that away from source and put in another place like a notification seems to be the best solution.

Sean said...

eclipse has a similar header that I always find in projects at work...

Emilian Bold said...

Oh, yes, it's not just a NetBeans thing, it seems to be a common IDE usability error.

XCode for example also does something similar by introducing some copyright header which is usually wrong as it assumes a single company while one might have multiple customers, or assumes the username is the actual author. People commit this autogenerated stuff all the time!

Mohamed El-Beltagy said...

You are absolutely right. This comment is annoying. For every fresh install of Eclipse or new workspace I create, the first I do, I go and change the templates:
1- Code generation template
2- Some of the javadoc templates
3- the author template

and I also, setup the formatting options to my needs in Java/HTML/XML formatting.

It's one of the things I do as a post installation or post workspace generation.

And when I am working with a team, I export my settings and force my team members to import them and change the required options as well.

This way, we guarantee to have a clean and unified source code base in our project.

mikeb said...

Interesting point although I strongly disagree with you. An important facet of designing any system, whether an IDE or a small library, is how it encourages users to program. Is the easiest, most obvious way to use an API to copy & paste code or by violating another best practice? Then the API is encouraging users to program poorly. A positive example is the Pattern class that encourages precompilation and reuse which fits its implementation very well. The salient point being a system or API should guide its users down the best possible path and encourage the best possible practices. This relates to the topic of IDE code templates in that its providing you sound guidance, document your code. Should the IDE instead make it easy and in effect guide users to writing undocumented code? For the people who document their code this is a valuable feature and welcome reminder. For those who don't its a 30 second detour editing a few lines of text. So should we cater to programmers who are too lazy even to change three lines of text to continue on their haphazard endeavors of polluting the web with yet more undocumented, incomplete software? Personally I think we should change the template to "IF YOU SEE THIS MESSAGE DON'T USE THIS SOFTWARE". One practice I strongly agree with is programming against documentation, not implementation, and I've never seen well documented code with that text in it.

Neil's netbeans stuff said...

I agree too, one of the first things I do is change the templates after installing netbeans.

The ide should not insert "ide help" code into a source file.

At least with netbeans you can export and import option settings.

osbald said...

Even more annoying are the default Eclipse and IntelliJ Idea templates that contain TODO tags. This tends to pollute the TODO tasks with empty, repeated comments. Applies to every new class, every generated catch block etc..

Emilian Bold said...

I had forgotten about the TODO tags!

Those are another bad idea using the same logic: if we overwhelm the user with inserts into the source code they'll do something about it: more often the result is just removing the TODO.

Usually they are useful since it saves the work of adding that reminder yourself.

But one shouldn't force best-practices on users, it should be an opt-in feature not opt-out.

The case of the different jsch 0.1.54 binaries

As part of the Apache NetBeans IP clearance we are combing through all the code and dependencies. One interesting thing we bumped into wa...