Dynamic help


I had an attendee come up to me today asking if they could talk to someone from VS-Core. ‘Core’ is the name that we use for the team that is responsible for the VS infrastructure that is shared amongst all languages. An example of this would be the editor. While the C# team is responsible for the C# editing experience, we fulfill that experience by sitting on top of the interfaces provided by Core. Of course, this isn’t a hard rule. The debugger is shared by all languages, however they’re contained with the C# team.

He was happy with VS as a whole, but wanted to give some critical feedback about Dynamic Help. The basic problem was that while he used (and liked) DH he didn’t like how having it open could affect the start-up time of VS. I agreed that that sort of a delay is quite frustrating and that we should work hard to fix up that issue. I also pointed him to Stephanie (a PM on the Core team) to let him talk to her directly about these issues

It got me thinking and had me start asking attendees what they used DH for. It turns out that big part of it is to get information about the structure of a class. I.e. if they type: “IList list”, then they’ll get the help on IList (using DH) so that they can know all about that class in a way that completion lists fail. They can see all the information at once, rather than just 8 lines as a time. They can see inheritance relationships and casts. They can see all the docs at once rather than method by method.

Well, it turns out that we’ve added something into the C# editing experience to help accomplish all these needs. It’s called the “Code Definition” window and it works like this: When your cursor is on a identifier we automatically determine the definition of that identifier and we show the code where that thing is defined in this window. For example of you have:

IList snarf;
//lots of code
Console.WriteLine(snarf);

If you then have your cursor on the ‘snarf’ identifier in the last line, then the code definition window will show the source code for this file centered on the line containing ‘IList snarf’. So right then and there you know what snarf is.

Another case is where you have your cursor on ‘IList’ in the case above. We’ll then show you the code for IList in the definition window. Now, chances are you don’t have the source code for IList, so what we’ll do instead is take the metadata for System.Collections.IList and we’ll convert it into pseudo-C#. We’ll even take the XML doc comments and we’ll insert it above all the class/method definitions. I call is pseudo-xml because while it’s grammatically correct, it’s uncompilable. For example, say you’re looking at the definition of ArrayList. We’ll spit out something like:

public class ArrayList : //some bases and interfaces
{
      //lots of stuff

      int Count { get; set; }

      //lots of stuff
}

i.e. we’ll spit out the signatures of methods, but not the bodies (although that would be a fun project decompiling IL).

Having this capability seemed to meet all the needs of how people tended to use DH. The places where it doesn’t are when you want help to stay up in a separate window and you don’t want it to change when you move around in your file. It also doesn’t help when you are looking for things that are help only (like examples). So I was wondering how people here felt about DH. Do you love it/hate it? Either way, why? I’ll work on getting some images up of the Code Definition window, but before i do that, feel free to give me some thoughts on if you like the idea, or are looking for something else.


Comments (20)

  1. Scott Hodson says:

    I use a separate window, the integrated help is too slow and puts too many tabs in my tab bar.

    I also do a lot of Java development and IDEA IntelliJ is my favorite Java IDE, moreso than VS.NET. I can press Ctrl-Q on any identifier and get the full JavaDocs to pop-up in a separate, anchored, scrollable window. If there’s no JavaDocs defined, like a user-defined type that hasn’t been documented, it’ll show the method signature and return type. No need to have a separate window of JavaDocs open.

    One thing I’d like to see is if, while on a identifier, I select "Go to Definition" and then, after going there, I want to go back to where I was before, there doesn’t seem to be a way to do that. VB6 can do that, F2 and, I think, Shift-F2 to go back. I miss that.

    While I’m ranting here, if I say

    ArrayList someList = new

    I would expect "ArrayList" to pop-up in a list, already highlighted, and any other known sub/supertypes of ArrayList to be close to the highlighted "ArrayList" option, instead of having to scroll through the entire list or type the first N keys to find my class. I’d expect a little more intelligence there.

  2. anonymous says:

    > although that would be a fun project decompiling IL

    It’s already done, download Reflector – http://www.aisto.com/roeder/dotnet/ – and get that Smalltalk feeling back. Take note of not just the decompiled code, but the hyperlinking in the code window and so forth. It’s not perfect, but having something like it integrated into the VS editing environment would be incredible.

  3. Scott: Rants are good. Rant more.

    a) There is a way to go back after go to definition. It’s some keystroke that I can’t remember now. Ping me in a few days when i’m back at the office and I’ll look it up. You can then rebind it to something more useful to you.

    b) In whidbey we’ve bound that action to the back-button on the mouse (if you have one of those 5 button mice).

    Your proposal for the completion is quite interesting and we’ll look into that kind of action. The biggest issue we see is that completion lists have been around for a long time and people have an expectation of how they’re supposed to work (especially how they’re supposed to sort). Another similar kind of idea is how we would react to:

    throw new

    You’d almost expect us to give you a list filtered down to Exceptions only. However, that would screw you up if you wanted to type:

    throw new MyClass().GetSharedException();

    Rare we know, but people do some pretty funky things (especially in large complicated applications).

    We’re looking into ways to do this better and I’ll add a post on this later.

  4. Anonymous: Reflector gives you a pretty good hierarchical view of your metadata. However, it doesn’t give you a view that looks like C# code. We’d like a seamless experience between viewing a definition that comes from your own source and one that comes from metadata. If we had a system like .net reflector, then it would be like the current model where we take you to object browser.

    I was referring to taking the IL and producing C# code from it. It would be a fun exercise, especially taking some of the new language features like anonymous delegates and iterators and producing something similar to the original source.

  5. Stu Smith says:

    A couple of trivial yet annoying points:

    1) Help doesn’t remember its desktop state and position. Hit F1, then maximise the window. Close it and F1 again, and that’s fine, but if I restart devenv and F1, the window should open maximised again. Opening in the restored state is way too small.

    [And a related point — why does help like SQL Server BOL open filling the screen but not actually maximised?]

    2) Why does help share its favourites with IE? I’d never want to open my IE favourites in help, and equally I’d never open my devenv help favourites in IE. I’d much prefer them to be two separate lists.

  6. nfactorial says:

    I disable DH (or any embedded help within VS) after a fresh install and never enable it again, it was just too slow. If I need help I start up an external version of the .NET documentation or MSDN help (depending on which language I’m using).

    n!

  7. Saurabh Jain says:

    Stu,

    1) I am going to investigate why doesn’t the external help viewer restart in maximized mode. No promises, but we will try to get this fixed in VS 2005.

    2) We are fixing the issues around Favorite in VS 2005. Help favorite window no longer shares favorites with IE, you can import and export favorites across machines and you can even save favorites search (you click on the stored search, and we will reexecute it for you).

    As for dynamic help, we have done some work to make it less in the face (like not having it visible at startup in the default window layout, not bringing it up when user hits F1, etc.).

  8. I hate to say it, but dynamic help blows. It just brought my machine to a halt, and I disable it on every new install, like another of the posters indicated he/she did.

    However, some of the features being proposed are interesting, to say the least. The comment about generating "pseudo-code" was amusing to me, only because someone will eventually make a plugin that will give you decompiled code a-la Reflector if it can’t be found in any of the loaded projects.

  9. D. Brian Ellis says:

    I hate dynamic help. If I had the power I would put it in a corner to think about what it’s done wrong and come back when it has changed.

    1)It’s slow (think, 5 sec. start times and I have 512 mb of memory)

    2)It continually re-opens when I have not asked for it and above all, it has no useful information for me.

    3)If I’m working with some myClass object. I don’t get myClass definition as a link, I don’t get info on things I can do with this class (Interfaces, Reflection, etc.) No, I get the same 10 boring overly general topics (C# Samples, Customizing the development environment).

    I think the DH is a GREAT idea, but the current incarnation is bad, bad, bad.

  10. Jason Hasner says:

    At home, DH is slow but still faster than me searching manually. At work, (1 Gig ram, 3 Ghz) it’s fast enough. It is one of the features that made me fall in love with VS in the first place. I use VS almost exclusively, so I don’t have the exposure to different IDEs that others here can use to provide more constructive feedback.

    I don’t understand what Brian means when he says it opens when he doesn’t ask for it… probably because I don’t use it the same way. It’s a tab docked to the right side of VS and I expand it when I need it. It doesn’t seem to populate until I expand it. So it only uses resources when it’s needed and then it only takes 1/2 a second to populate. After the first time, it’s even faster.

    I would agree with the feedback about "the same 10 boring topics" and the lack of info on user defined classes, but I also understand why those decisions were made.

    All in all, very well done. Keep up the great work.

    You guys should go have a talk with the source safe team. That app pisses me off on a daily basis.

  11. I, too, always work with a seperate help window. The DH’s lag is only a fraction of a second, but it really annoys me when I walk the code. The code-definition window you mentioned sounds like a GREAT idea.

    Btw, The key-combination to go back to the last place you were in the code (not only after an F12, but regardless) is Ctrl– (That’s Control-Minus). Took me a while to find out about it, but it’s a lifesaver.

  12. Nicholas: Don’t ‘hate’ saying anything. We don’t write features saying "i really hope people won’t like this". We want you to be saying "i can’t live without ‘blah’". By telling us if something isn’t good enough, we can fix it, or replace it with something better. All we ask is that you help us understand what does/doesn’t work with your development process.

  13. Avner: Thanks for the ctrl– tip (looks like a alternatice to C++ doesn’t it).

    If you get a chance, try out the VS beta and let us know if you like it or not.

    Could you explain why you are annoyed when you walk the code?

  14. Saurabh Jain says:

    Jason,

    Brian is talking about the case when DH pops up when you hit F1. The reason it happens (in VS 2002, 2003) is because we used DH for disambiguation, i.e. to show various alternatives available. This is however not discoverable and it just annoys people. We have fixed in VS 2005 by not using DH but instead showing the alternatives as a drop down off the browser window. For VS 2002, 2003, you can use the VSTweak (http://www.gotdotnet.com/team/ide/helpfiles/vstweak.aspx, a VS powertoy) to disable this F1 popup issue. Scott has talked about these changes at http://blogs.msdn.com/scottsw/archive/2004/03/30/104314.aspx#111440.

    Also, if you look at Tools->Options->Environment->Dynamic help, you can uncheck all categories except Help (and may be Action and Misc.). This should reduce the amount of static links in your window.

    Nicholas, I have never heard about DH halting up the machine. I do know that it does add 2.5 sec to the cold startup of VS on a 500 MHz, 128 MB, Win2K machine (I do have hard data to back my numbers).

    Yes, we do realize that DH doesn’t meet people’s expectations in many areas and hence we have done work to make it less in the face and reduce the annoyance and hatred around it. We are always open for more suggestion on how to fix it. But be warned, as we are in late stages of VS 2005 and we have more higher priority stuff on our plates and hence these changes most likely wont make into 2005 (unless it is cheap to do and improves the experience).

  15. Saurabh: I’ve also hit the issue where having DH up can dramatically affect start up time. On the order of far more than 2.5 seconds. I dont’ know if it’s related to disk or network activity but I do know it’s somewhat aggravating as you sort of sit their wanting to use the IDE but unable to do so because everything is locked.

  16. Taylor Wood says:

    Check out "Anakrino" for .NET. It generates compilable C# from a .NET assembly.

    http://www.google.com/search?hl=en&lr=&ie=UTF-8&q=anakrino&btnG=Search