Making “Promote Local” make sense.

We’re sitting around watching a video from a usability study.

A subject has been exploring the Refactoring menu, and has just tried Promote Local. With the help of the very specific error messages I wrote (yay exceptions), he finally gets it work.

On the audio track you hear him thinking out loud, describing what just happened – how the code was just transformed. Then he goes quiet. 4 full seconds of complete silence.

“Oh, WOW”.

<another pause>

“That… Now I understand the value in that; that’s a HUGE time saver”

And goes on to talk about how it’s a great productivity boost.

The video was sent under the heading “A feel-good video clip for you”, with the comment “This is what we would like to see as the standard user experience for new releases”.

Sure, it sounds good to hear someone say they like one of our features so much. But it also makes re-enforces my concern that Promote Local isn’t discoverable. Most people will look at the menu item, wonder for a moment what it means to “promote” a local, and then move on. The name doesn’t seem to resonate with most users.

The problem seems to be made worse by the fact that Promote Local has no option for Preview Changes. That’s mainly because there’s no UI that could offer that option; the feature is very streamlined. If you’re feeling inquisitive enough to try to run the Refactoring, you won’t get the expressive feedback from Preview about how it changes your code.

We’ve been brainstorming a bit about how to rectify the situation.

Perhaps we should rename the feature (and menu item).

The feature is meant to fill the Add Parameter space, so maybe we should call it that. Of course, you’d be pretty surprised to have Add Parameter fail because the cursor isn’t on an initialized local variable.

We could do “Add Parameter from Local Variable” or “Add Local Variable as Parameter” or something. Those names seem a bit clumsy, but maybe they’ll do the trick. If you’ve read Fowler, you’ll probably expect to find an Add Parameter Refactoring.

One thing we probably should have done is made the menu items dynamic, inserting symbol names in them. So “Rename…” becomes “Rename Foo…”. Thinking along those lines, we could do “Promote Local Variable ‘foo’ to Parameter” “Promote Local Variable ‘foo’ to Parameter of ‘F()’” or “Make Local Variable ‘foo’ a Parameter of ‘F()’”.

One option suggested by a reader is to link to my sig change blog from a tool tip. <wink>

I’m going to see if I can help the documentation folks get really good docs for Promote Local into the product. At least that way, if you do go looking at help you’ll figure it out. But I don’t expect most people will do that.

I need your help. How can I make it clear what Promote Local is? What would you like to see in the product?

Comments

• Anonymous
  July 29, 2004
  'Local Variable->Paramater'?
  
• Anonymous
  July 29, 2004
  Convert Local to Parameter?
• Anonymous
  July 29, 2004
  Why not simply "Promote Local to Parameter"?
  
  If the cursor happens to be somewhere where the refactoring isn't allowed, show a dialog explaining why. Offer a link to a /helpful/ help section. Include the option to turn the dialog off.
  
  The dialog could be replaced by a beep, and the text could be written to the output window, the statusbar or something.
• Anonymous
  July 29, 2004
  I was also thinking of "Promote Local to Parameter".
• Anonymous
  July 29, 2004
  "Promote local variable to parameter" sounds quite descriptive to me. Just having "Promote local to Parameter" did not make intuitive sense, to me anyway.
  
  How did you come up with "promote"? The scope of the variable doesn't really change, assuming that the local variable wasn't inside some sort of loop or using statement, so I don't understand why it is "promote". Maybe I'm just being picky or I'm not in tune with the use of promote in this sense.
  
  Why not "Make local variable a parameter"? Oh well, all suggestions.
• Anonymous
  July 29, 2004
  The comment has been removed
• Anonymous
  July 29, 2004
  There are two concerns here as I see it
  1) The name of the menu
  2) The context in which menu (feature) works
  
  The first concern is addressed pretty easy; Renaming menu to ‘Convert <variable name> to Parameter’ solves it as well as any other suggestion above that has ‘variable’ and ‘parameter’ words in it.
  The context is trickier, if you need to click on the variable to get menu item to work – than it is cumbersome. Why would I click on the initialized variable unless I already known about ‘promote local’? And If already known how to use I do not care about the form it is implemented. How about this:
  If you click on variable – you add menu item ‘Convert <variable name> to parameter’, but If I click inside a method body I would get ‘Convert variable to parameter’ and submenu with names of all initialized variables. If I select any of the variables – the code adds it as parameter.
  This way user can discover this feature while doing some other work on the method, user is not required to aim his/her mouse to the variable declaration, the menu is clear about what will happen and feature is more readily accessible.
  Home it helps.
  Sergiy Mesropyan
  
• Anonymous
  May 31, 2009
  PingBack from http://woodtvstand.info/story.php?id=8306