Inheriting comments

by Manu (modified: 2008 Feb 18)

I don't know if you are like me but often when you redefine a feature, I used to copy/paste the comments so that I still know what the feature is supposed to do in english terms (in addition to the contracts of course). In 6.2, we are introducing a new facility so that in the editor and in the flat-view of the feature you do not have to do the copy/paste.

I'm going to use classes from the compiler to show the new feature. The definition of {TYPE_A}.good_generics states:

good_generics: BOOLEAN is -- Has the base class exactly the same number of generic -- parameters in its formal generic declarations? require is_class_valid: is_class_valid do Result := True end

and now in my descendant LIKE_TYPE_A, I just do the following:

good_generics: BOOLEAN is -- <Original> do Result := actual_type.good_generics end

Basically, what we are doing is that the comment -- <Original> is a placeholder to get the inherited comment. In the EiffelStudio editor, it is shown by the following tooltip when you leave your mouse pointer over the feature name for a few seconds:

Showing inherited comments inline in EiffelStudio

Note that if you do put no header comment in the redefined routine, we will still show the inherited comment. However it was felt that having -- <Original> was a clear indication for the reader of the class that the header comment was not forgotten.

And if you inherit the routine from various ancestors, you can choose which ancestor's comment to take by using the following syntax -- <Original {MY_ANCESTOR}>.

If you have any feedback on this new feature, please let us know by dropping a comment.

Comments
  • Paul Bates (16 years ago 19/2/2008)

    Original comments, everywhere

    For those that have read your blog, as of rev#72341 the inherited/original comments can also be seen in the code browsing tools such as the Features and Class Tools.

    Also, it's worth mentioning that the <Original> comment can be injected anywhere in a redefined feature's comments, it's not an exclusive system. It is entirely possible to author new comments for a new feature and implant <Original> on one of the new lines. The end results merging the written comment with the inherited comment of a redefined feature.

  • Peter Gummer (16 years ago 19/2/2008)

    I have a comment

    -- <Original {MANU}>

    • Peter Gummer (16 years ago 19/2/2008)

      Precursor

      But seriously, why not use the same keyword that Eiffel code uses to denote the inherited routine:

      -- <Precursor {MANU}>

      Then people only have to remember one word. You'll have newcomers confused trying to remember which word they have to use in which context.

      (Not that I'm particularly fond of the keyword Precursor -- I would have found inherited more intuitive -- but Precursor it is, so let's use it!)

      • Manu (16 years ago 19/2/2008)

        We thought about Precursor, but because it refers to an implementation rather than to a specification we thought something else would be better. This is why we have settled for -- <Original>; this is definitely not a firm decision yet as we are waiting for more feedback.

        • Peter Gummer (16 years ago 19/2/2008)

          Comments are clearly not implementations

          If it appears in a comment, it's clearly not referring to an implementation, so I can't see any opportunity for confusion if you use -- <Precursor>.

          But if you really don't want to do that, then how about:

          -- <ditto>

          Which people might abbreviate to:

          -- <"> 

          ;-)
        • Eric Bezault (16 years ago 19/2/2008)

          Precursor vs. Original

          The keyword Precursor refers to the implementation, but the notion of precursor feature is implementation free, as defined in ECMA 367-2, section 8.10.27: "A precursor of an inherited feature is a version of the feature in the parent from which it is inherited." On the other hand, Original may be confused with the definition of Origin of a feature, section 8.5.1, which is the class where the feature was first introduced. Considering these two definitions, I clearly prefer Precursor because what we mean is the comment in the precursor feature (i.e. the version of the feature in the parent), not the comment that appeared when the feature was first introduced. In the example below:

          class A feature f -- Comment 1 do ... end end class B inherit A redefine f end feature f -- Comment 2 do ... end end class C inherit B redefine f end feature f -- <Precursor> do ... end end

          what we mean is -- Comment 2 and not -- Comment 1.

          • Manu (16 years ago 20/2/2008)

            It definitely makes sense to use Precursor and we will go with it for now since it seems that people prefer it even though it is not used for implementation but for specification.

  • Greg Compestine (16 years ago 26/2/2008)

    Nice, but..

    Shouldn't the "Edit Contracts..." button be in a popup menu instead of a tooltip?

    This seems like a very non-standard add-on to tooltip functionality. I do think the tooltip is a good idea, and I also believe strongly that Eiffel Vision should be migrating closer to supporting standard behavior rather than adding more departures from it.

    If it is documented as a standard for Windows or some other common user interface, could you please refer me to the document?

    Thanks,

    Greg

    • Manu (16 years ago 26/2/2008)

      I'm not sure if there is any standard for tooltips, but if you look at Visual Studio they have something very similar. They do not have a button, but they have expandable tree views in the tool tip. Not exactly the same, but it looks like tooltips are not just messages anymore, you can interact with them.

    • Peter Gummer (16 years ago 28/2/2008)

      I like it if it works

      I have no problem with this innovation. Where I get annoyed as a user is when an innovation gets in the way of standard user interface conventions. (Pick and drop is the classic example of that. Until recently, it impeded the use of context menus, and even today there is no drag and drop.) In 6.2.7.2437, we have this nice preview of the contracts tooltip, and I like it, but a couple of times already it has popped up when I was attempting to right-click a feature.

      The trouble with this sort of thing is that it's easy to prototype and get people saying "Wow!", but it's very difficult to get it right. So I'd be glad to see this in 6.2, as long as it's very thoroughly tested! I would expect to see an option in Preferences for turning it off.

      • Paul Bates (16 years ago 28/2/2008)

        A few Notes

        We are aware of the right click issue and it will be addressed.

        I put a preview of the contract viewer in the editor to ensure any annoyances are worked out before the release. I mentioned this in one of the 6.2 release notes, release 6.2.7.2075.

        There are a few things that might happen with this:

        • The drop down is shrunk to a small beam under the feature name text, so it does not pop up accidentally or get in the way.
        • The pop up time out will be longer so it does not pop up too soon, with a key modifier to show it immediately.
        • It will be removed.

        We need to get this right because in the future the mechanism will be used in various forms throughout EiffelStudio. As it stands, what you see probably wont be what is released. There is quite a bit of logic already there to determine when to show the token options. Any feedback is welcome, we want to get this right without being annoying.

        In reference to Greg's remarks, it's not a tool tip. In the future you'll be editing contracts directly on the "assistance window". As I've said these types of windows will be placed through EiffelStudio in future releases, not just in the editor.

        • Peter Gummer (16 years ago 28/2/2008)

          The contract viewer's right-click issue

          Paul, you mention three possible fixes for the right-click issue seen in the sneak preview of the contract viewer.

          • The last would be sad, so let's not think about that.
          • The second would be disappointing: it's so neat that it pops up simply by hovering the mouse there.
          • The first is intriguing. You say that hovering the mouse over a feature would display a small beam. What would the user have to do, then, to open the contract viewer? Click on the beam? Move the mouse down a bit to hover over the beam? This sounds a bit disappointing too.

          A fourth option would be to leave it as it is, but make sure that right-clicking works. Isn't this possible? If I try to right-click on a feature but the contract viewer has popped up unexpectedly, is there any reason why the right-click can't be forwarded to the feature stone underneath? (Not sure if I've got my pebble-drop metaphors mixed up there, but you know what I mean.)

          Me, I'd want to activate it via a keyboard shortcut rather than a mouse-hover, of course ;-)