Tor Norbye's series of weekly screenshots of cutting edge NetBeans features is interesting, but the feature displayed in this recent one has made me wonder about the balance between what IDEs can do and what they should do. The feature is fairly simple, adding a type annotation to function/method parameters in python so NetBeans can recognize the expected type and grant semantic auto-complete for the parameters. In my opinion, this steps over the line of what an IDE should do. Here's why I think so.

What an IDE should do (when editing)

When I'm typing, I want the editing environment to enrich my ability to type. If I'm typing plain text, some sort of word-completion is a benefit. If I'm typing code, word-completion is useful, but semantic code completion can be much more useful. I say can, because sometimes the limitations of the IDE impede the usefulness of code completion. When the IDE doesn't know how to do the right thing, I often find myself yanked out the context of the code and either have to rearrange myself to what the IDE has done (in dynamic languages, often expanding every possible completion regardless of type) or consult an external source on what options are available. Both these actions are undesirable, because they take me out of my primary focus (the code). The code completion I've been doing up until this point has also conditioned me. I am conditioned by the IDE to use code completion as part of my writing process. When code completion fails, I have a failure in my writing process. It follows of this that it is desirable that code completion never fails.

When I am writing code, I'm generally writing just one language (or in some cases, such as php, erb templates, django templates, jsp, a markup combined with one language). Therefore, I want my editing environment to support the writing of that language. When I am writing Java, this means aggressive code completion, templating and creation. In fact, templating and code creation is actually more important to me in Java than code completion. Java requires a lot of boilerplate and ceremony, and the more of this the IDE can take off my hands the better. When I'm writing Python, I want the IDE to flag stuff like undeclared variables, missing imports, code style and many of the other things Nordbye has demonstrated over the last weeks. I do not, however, want code completion. Maybe this is because I don't write much code that interfaces with Python libraries, but I prefer word completion. But the primary reason I don't want code completion is that it will fail. I don't want to introduce failures to my writing process.

What an IDE should not do

Simply stated, an IDE should support the language in question. It should not expand the language. The commented type annotations in NetBeans change Python. Changing the language means that the code acquires noise when viewed in other editors. Other editors do not parse anything of value from the commented type annotations.

I also think that adding semantic value to comments is a bad idea. Since comments don't fail when code is updated, there is a very real possibility that a method's parameters can be updated without the type annotations being updated with them, possibly causing NetBeans to code complete for the wrong type. This is a failure, and the result is even worse than the failure above, since the IDE is now helping you write patently incorrect code.

What I'm suggesting

It's bad form to criticize without suggesting an alternative, so here goes. I don't know if this is feasible, and it's almost certainly more work than the type annotations were.

I would like my IDE to support my normal habits when I'm writing Python. What I was taught in my early Python days, was that the REPL is your friend. This is not just because you can test code snippets in it, but because Python is self-documenting. Documenting comments are generally not written with comments, but with docstrings. A great way to get help about something is to run some introspection on it, or use the dir() or help() functions. The dir() function lists all methods available on an object. The help() function provides a formatted and paged listing of a type and its methods.

What I would like is for my IDE to assist me in using these functions. For example, if I'm looking for some documentation on the str class (as Nordbye was doing in his example), I'd like to be able to view the results of help() on some type in a panel in the IDE somewhere. The exact way to input that type's name should be up to better interaction designers than myself, but some sort of dialog that accepts the typename bringing up a panel displaying the help page would be most useful.

The code completion mechanism could then rely on this documentation panel as a 'hint' when type inferencing fails. That said, it should probably be clear from the drop-down that completion is being done from the documentation, so it's clear to the developer why string completion is being done when I'm dealing with something I know not to be a string.

When I tried out the NetBeans nightly build for Python to get an idea of how intrusive the comments were (too much so) and how well the other stuff worked (very well), the only time I needed explicit type annotating failed. I was dealing with a dict filled with lists, and wanted a method for the list that I didn't know what was called off-hand. I was not altogether pleased by this, but the overall feel of doing Python development in NetBeans was quite good. Editing felt snappy and responsive. It was very easy to import my existing project (with a non-standard layout) to NetBeans and both navigating through the project and editing worked very nicely.