Tasklist UI issues

I just posted this document:
http://tasklist.netbeans.org/proposals/suggestions/ui-issues.html

I would appreciate your feedback on it.

Here's a .txt version of the document for your reply-convenience;
the HTML version has the advantage of inlined images.

-- Tor


I've been working some more on the tasklist module, and I've run into
some more UI issues. I think I'm getting close to completion now. I
would like some feedback on any or all of the following issues; I've
added my recommendation to some of them, which is what I'm going to
implement unless I get feedback.

I hope I've remembered to include everything that I've been wanting
feedback on. I realize this document is a bit long so don't feel like
you have to comment on everything - just pick and choose what you want
to address.

First a quick update from my last nbui post, where I was wondering how
to deal with the fact that you get lots of suggestions, so how does the
user manage these. I settled on adding "category nodes" and placing
suggestions under each category. Here's what this looks like:

http://tasklist.netbeans.org/proposals/suggestions/categories.gif

The next thing I added was a confirmation panel. The goal of this panel
is to tell the user what the action is going to do, in case the user
wants to decide if this action is what s/he wants (and possibly, the
confirmation panel could have knobs where the user can affect exactly
what is done).

http://tasklist.netbeans.org/proposals/suggestions/confirmation.gif

One of the really handy things I've implemented is the ability to multi
select suggestions in the view, right click and select "Fix", and then
it will iterate over all the suggestions and fix them all.

*Issue 1*: What happens to the confirmation dialog in this case? For
now, I've simply added a "Fix All" button to the confirmation dialog
which lets you skip through all the confirmation dialogs for each
suggestion being performed. Would it be better to provide an
"integrated" confirmation dialog, listing ALL the suggestions about to
be performed - if so, how would this work? Place all the confirmation
panels inside a large scrollpane? (with a checkbox next to each?)
Somehow get related confirmations (each all the unused import
statements) into a single confirmation panel just listing each
suggestion on a line with a checkbox? Other ideas?

*Recommendation*: For release 1.0, just bring up the confirmation dialog
for each suggestion in succession. Use the "Fix All" button to allow
users skip the confirmation step for the remaining suggestions.

*Issue 2*: As you can see from the confirmation dialog screenshot, there
is a checkbox named "Skip confirmation next time". When the user checks
this, the user is never prompted again for suggestions of this type -
they are simply performed.

   1. Should I have a "Stop making suggestions of this type" checkbox as
      well, making it easy to get rid of suggestions of a particular
type?

      *Recommendation*: No. It's easy enough to do this from the context
      menu: simply right click on a suggestion and select "Disable
      Type". If you change your mind, select "Re-enable Types >" which
      is a pullright menu containing a list of the suggestion types
      which have been disabled.

   2. How does the user "undo" the action of removing confirmation for a
      particular suggestion type? Right now the only way to do it is to
      disable the type and reenable it.

      An obvious solution is something similar to the one I have for
      enabling/disabling types, described above. But this starts to get
      silly: 4 items in the context menu for controlling
      enabled/disabled, confirm/don't confirm for suggestion types.
      Perhaps a better solution is to integrate this into a single
      dialog. But what should the menu item be called ("Types..." ?),
      and what should the dialog look like? Perhaps:

                   +----------+               +----------+
          Enabled: | Copyright|    Disabled:  | Rule Viol|
                   | Parse    |               | Source Cm|
                   | PMD      |     <<<       |          |
                   |          |     >>>       |          |
                   |          |               |          |
                   +----------+               +----------+

                              +---------------+
                              | Parse         |
          Skip Confirmation:  | PMD           |
                              |               |
                              |               |
                              +---------------+

      *Recommendation*: Needed - please provide suggestions. 

*Issue 3*: Should I add a "Fix All" action on category nodes so that you
can easily operate on a set of suggestions without needing to make a
selection (which often involves scrolling when there are lots of them?).

Because of issue 1, this would only produce a confirmation dialog
stating that all suggestions will be performed (to give you a chance to
cancel) and perhaps list the summaries for each with checkboxes to let
you unselect some. Also, suggestions for this category that do not have
associated fixes (for example, because it cannot be done safely; for
example, an unused field on a line containing method calls will not have
an associated fixer since the unused method could have an important side
effect.)

*Issue 4*: For java compiler errors, I list both the errors themselves
(strictly speaking, these aren't "suggestions", but it's quite helpful
to see them while you're editing source so you don't have to mouse over
the error glyph in the source code) as well as suggestions for how the
errors can be fixed (when I can think of a solution). For example, if
you have a "undefined symbol: class List" error in Foo.java, I add two
suggestions:

    * Import java.util.List into Foo.java
    * Import java.awt.List into Foo.java 

So, you end up with three items in the view; the last two are solutions
to the first. How do I show relationships like these?

Some solution ideas:

    * What I have now: a different icon for solution suggestions, which
      hopefully draws you attention to them.
    * (*My favorite*) Nest solutions as subnodes of the problem item
    * Others? 

*Issue 5*: Let's say you've got a compiler error on the current line
(you see a red squiggly line in the editor on the current line) but the
error seen first in the Suggestions window is not relevant; because
there is another error in this file further up.

To make it easy to catch this situation, and to see which compiler
errors apply to the current line, I'm now marking (badging) the
suggestion icons for suggestions applying to the current cursor line
with a cursor-like badge (a black vertical line). Look at the
suggestions for line 99, where the cursor is located:

http://tasklist.netbeans.org/proposals/suggestions/linebadge.gif

Is that a reasonable visual cue? I wanted to make the current line bold,
but well, take a look at the nbdev discussion on this (rendering hints,
started by Tim B.)

*Issue 6*: For PMD rules in particular, I tend to get LOTS of rule
violations. For example, I may have 30 unused imports in a class
(because it started out as a copy & paste from a different file), or I
may have violated a particular rule because I don't agree with it (e.g.
the "OnlyOneReturn" rule in my case.)

I was thinking that it might be nice to "group" a series of "identical"
suggestions (where they are identical in the description, but not in the
file and/or line number) into subnodes.

However, this seems like a special case of a more generic problem: PMD
in particular exposes something similar to "subtypes": "Rule Violations"
is the suggestion type, but within rule violations, there are lots of
subtypes of suggestions: unused imports, unused variables, duplicate
imports, etc. etc. Perhaps I should make it possible for modules to
register these subtypes such that these suggestions can be grouped? In
other words, you'd have

  - Rule Violations
    - Unused Imports (3)
         Unused import: Avoid unused imports such as 'HashSet'
         Unused import: Avoid unused imports such as 'Map'
         Unused import: Avoid unused imports such as 'File'
    - Unused Local Variables (1)
         UnusedLocalVariable: Avoid unused local variables such as 'xyz'
    - Unsafe Coding Practices (1)
         OnlyOneReturn: A method should only have one exit point

And possibly, if there are less than N suggestions of a particular
subtype (where I propose N=3), they are "inlined" at the top type level,
e.g.

  - Rule Violations
    - Unused Imports (3)
         Unused import: Avoid unused imports such as 'HashSet'
         Unused import: Avoid unused imports such as 'Map'
         Unused import: Avoid unused imports such as 'File'
      UnusedLocalVariable: Avoid unused local variables such as 'xyz'
      OnlyOneReturn: A method should only have one exit point

*Issue 7*: Let's say I allow subtypes as proposed above. How does this
show up elsewhere, for filtering and disabling types?

Right now I let you disable types by right clicking in the Suggestions
View, and in the Disable Type pull right pick the type of suggestion you
want to suppress.

It would be nice if you could use this infrastructure for the subtypes
as well; for example, you no longer want to be notified of the
OnlyOneReturn error - but you don't want to disable all PMD suggestions
- only that one instance. Well, you can use PMD's option panel. But that
solution will vary from one suggestion type to another. It would be nice
if this infrastructure could be used on subtypes as well.

Here's how I think this can be solved: in the "Show" menu, which
currently looks like this:

http://tasklist.netbeans.org/suggestions_v2_popup.gif

I should add another separator, and then list all the types that have
subtypes as pullright menus. For each pullright menu all the subtypes of
that type are listed as radio buttons, just like at the parent level.

Another alternative is to somehow hook up to "native" customizers for
types that have subtypes. For example, for PMD suggestions, disabling a
type would bring up the PMD rule selector. But I'm a little unclear on
how this would work, so if you like this approach, be specific about
what exactly should appear where.

*Issue 8*: Right now, most suggestion providers provide suggestions when

   1. a document is opened
   2. the current document changes (user selects another tab)
   3. the current document is edited (after a brief (2 second) delay) 

Is that the right thing to do? Or should rescans be triggered by
something else? For example, an alternative scheme could be

   1. a document is opened
   2. a document is saved 

In other words, should the suggestions window reflect the current,
edited state of the document, or the on-disk, saved state of the
document?

*Issue 9*: I'm showing "category nodes" for the types of suggestions.
What should happen if the number of suggestions of a particular type
goes down to 0 - should I remove the category node from the display as
well? For example, this easily happens if you're looking at a file with
compilation errors and then switch to a different file. Should the whole
javac compiler error node disappear or simply have no children?

*Recommendation*: For now I'd like to leave it there. It's an easy
implementation way to ensure that the collapse/expand state of a type is
preserved, and that the relative order of the types do not change as you
traverse files in the editor.

*Issue 10*: I have some "automatic fix" operations in the PMD
integration and javac parsing integration modules. For example, if a
field is reported as unused, double clicking on the exception will
remove the field.

But what if the user had a comment above the field associated with that
field - should I remove the comment too? And what if there are multiple
comments?

Unfortunately, I cannot do the right thing here, since I cannot
interpret the comments and discover if you have a scenario like this:

  /** description of the unused field */
  // Don't forget to get rid of this
  private int unused;

or

  /** description of foo */
  // int foo = 5;   temporarily removed
  private int unused;

So the question is what I do about this. Should I perhaps have a
confirmation dialog which lists the lines surrounding the field (with
checkboxes for each) letting you choose how much should get deleted?

*Issue 12*: The Suggestions Window, as is obvious from the name, was
intended to list suggestions, not tasks in general. There's a separate
"User Tasks" window where users can enter tasks for themselves. In fact,
you can create separate tasklists, one for each project for example (in
the New From Template dialog), and opening each tasklist creates a
separate tab for it.

Other IDEs have a single tasklist where all this (compiler errors, user
tasks) appear in a single window. Should we make it possible to add user
actions in this view as well? How high a priority is that? And if so,
should we change the name of the window to "Tasks" instead of
"Suggestions" ? (The fact that I'm listing both compiler errors, and
tasks scanned from source code (// TODO and so on) already makes this
relevant I think.

*Issue 13*: Related to the above. I've made it really easy to filter the
Suggestions View such that you only see one type of suggestion; for
example, if you choose "Java Compiler Errors" you only see those errors,
and the "category node" for these is hidden. (Also, the icon and tab
display name are changed from "Suggestions" to "Java Compiler Errors".)

I was thinking it would be nice if you could create multiple versions of
the Suggestions view and filter each individually. That way you could
open one and make it show your editor scanned tasks (then I could get
rid of the docscan editor view which lists precisely this - comment
tasks in the current file), and another one showing you compiler errors
for example.

Right now if you click on the Suggestions View icon it will only open or
front the existing one, not create additional instances. Is that the
right way to do this, or is there a better way? (A "New" item in the
View's context menu, etc.)

*Recommendation*: I'd like to push this out to version 1.1.

*Issue 14*: Currently, when a new category node is shown, it's not
expanded. You have to open it yourself. This has the advantage that when
you first open a new file, you quickly see what suggestions are
available:

    * Java compilation Errors (4)
    * Rule Violations (7)
    * Source Comments (1)
    * Copyright Warnings (1) 

On the other hand, it's annoying that I have to manually open the Java
compilation errors node to get to see the errors - these are critical so
I need to see them soon.

If I were to switch to a scheme where new categories are automatically
expanded, then you have to collapse everything by hand to see what's
available - you'll just see some compiler errors and some rule
violations.

Is there a better heuristic to use here? Hardcode that java compiler
errors is "special" and make it expanded by default, all others
collapsed? Make the APIs such that a provider can declare itself
"important"? Use suggestion priority to decide whether a category should
be expanded: true whenever there is one or more suggestions with
priority high in that category? Other ideas?

*Issue 15*: I've added a "directory scanner" which lets you request
suggestions for a directory (recursively). This creates a new tab with
the suggestion results. Let's say you decide to apply fixes to a number
of files in this suggestions window. When should the files be saved?

*Recommendation*: Files that were already open in the IDE should not be
saved. Any files that are "opened" only to apply a fix should be saved
immediately after applying the fix.

Wow, thanks for getting this far!

------------------------------------------------------------------------
Tor Norbye <mailto:[email protected]>