none
Naming scheme for methods/properties returning IObservable<T>

    General discussion

  • Are there yet any official naming schemes for writing code that exposes IObservable?

    For example: Is it recommended to return an Observable from a method or a property and should the name indicate the IObservable return type (I use MouseDown as the name of an imaginary event/value source)?

    Here a few examples of longer names:

    IObservable<T> GetMouseDownObservable();
    IObservable<T> MouseDownObservable { get; }
    IObservable<T> MouseDownAsObservable { get; }
    IObservable<T> MouseDownEvent { get; }

    .. or perhaps might it be better to reduced to the event name as a real replacement for multicast-delegate based .net events?

    IObservable<T> GetMouseDown();
    IObservable<T> MouseDown { get; }

    Which IObservable naming scheme do you personally use/like most? Would be glad to hear your opinion/suggestion.
    Wednesday, December 30, 2009 10:48 AM

All replies

  • Good question.  I tend to not like putting the type in the name so that would exclude the first four.

    I really like the property but of course it clashes with the event so that doesn't work.  I tend to go with GetMouseDown or a plural named property.

    event ... MouseDown;
    IObservable<T> ... MouseDowns;

    or

    event ... MouseDown
    IObservable<T> GetMouseDown();

    I also liked the pattern here.
    Friday, January 08, 2010 8:52 PM
  • > I also liked the pattern here .

    The Clarius Reactive Extensions Generator is really pretty cool. I think for events the ultimate thing would be a C# language extension allowing it get an Observable without detours directly from an event.
    Friday, January 08, 2010 10:13 PM
  • Agreed.
    Friday, January 08, 2010 10:19 PM
  • Hi,

    At first the pluralization idea seemed nice, but after some thought it appears to be too fragile because it relies on English conventions (consider events that end in "s", etc.) and also it's not explicit enough - easy to miss "s".

    How about these?

    IObservable<T> UponMouseDown { get; }
    IObservable<T> WhenMouseDown { get; }
    IObservable<T> MouseDownCallback { get; }
    IObservable<T> OnMouseDown();

    That last one will overload the event raiser method (different cardinality).  My opinion on this one toggles :)

    - Dave

     


    http://davesexton.com/blog
    Saturday, January 09, 2010 11:29 PM
  • Hi,

    If Subscribe was renamed to EndWith, that would compliment StartWith and would also enable the following format:

    IObservable<IEvent<MouseButtonEventArgs>> WhenMouseDown { get; }
    
    button.WhenMouseDown.EndWith(e => Console.WriteLine(e.EventArgs.X));

    Just a thought ;)

    - Dave
    http://davesexton.com/blog
    Saturday, January 09, 2010 11:43 PM
  • At first the pluralization idea seemed nice, but after some thought it appears to be too fragile because it relies on English conventions (consider events that end in "s", etc.) and also it's not explicit enough - easy to miss "s".

    How about these?

    (..)
    IObservable<T> WhenMouseDown { get; }


    Hi Dave,

    When is a great prefix! Thank you very much for that idea. First I thought OnXyz would be the best but it collides with internal OnXyz() methods (protected virtual)...

    Subject<Unit> whenSomethingHappened;
    IObservable<Unit> WhenSomethingHappend { get { return whenSomethingHappened; }}
    Worked for me now very well in a lot of situations. :)

    Andreas
    Wednesday, January 13, 2010 11:12 AM
  • Hi Andreas,

    Agreed. When is my preferred choice as well.  It just makes so much sense when you see it used in observable queries of any kind.  And it has the added benefit of being a prefix, so all observable members will be grouped together in Intellisense (although in VS 2010 you could type "w h e n" and it would even include members that don't use it as a prefix ;)

    I'm also wondering if it makes more sense to use the past tense instead of the present tense for observables.  Given their async nature, it seems more intuitive to think of events as having happened already before subscribers receive their notifications.  On its own, however, past tense is not enough as a naming convention because it seems to suffer from the same problems as pluralization does (see my response above).  Together, When and past tense seem to make sense.

      var clicks = button.WhenClicked; // is better than WhenClick
      var downs = button.WhenMouseDown; // can't make it past tense

    - Dave

    • Edited by Dave Sexton Wednesday, January 13, 2010 12:15 PM This forum needs to improve its support for inserting code. It's horrendous - and shocking given the forums typical usage.
    Wednesday, January 13, 2010 12:13 PM
  • var clicks = button.WhenClicked; // is better than WhenClick
     var downs = button.WhenMouseDown; // can't make it past tense


    I think your variable names give a hint to what the property names should be.  I'm not keen on When because it's not a noun.  The observable is a collection of things, so it should be named like a collection, which is probably the plural of the data contained in the collection.  Thus:

    var clicks = button.Clicks;
    var downs = button.MouseDowns;
    
    var downPositions = button.MouseDownPositions;
    Assuming the observable has transformed the raw event stream, eg gives a stream of mouse positions and not just the raw MouseEventArgs, then the naming becomes clearer?
    Wednesday, January 13, 2010 12:27 PM
  • The problem I have with the "plural" style is that a lot of times only one value will be observed. For example this is the case with every AsyncSubject which is created by calling the actions returned by Observable.ToAsync().

    var asyncMethod = Observable.ToAsync(ASyncMethod);
    var whenCompleted = asyncMethod();
    whenCompleted.Subscribe( ... );
    // ...

    is better (in my opinion) than

    var completions = asyncMethod();

    because I exactly know that there will be only one OnNext()+OnCompleted() or one OnError() call...

    For events I have now always used the original event name with the "When" prefix. In general this gives a quite consistent style to name member and local observable variables as well.
    Wednesday, January 13, 2010 12:44 PM
  • Hi,

    As Andreas pointed out, the consistency (and readability) of When across members and types makes it nicer than pluralization, IMO.

    The problem with treating IObservable<T> as a collection of things is that it's actually a maybe-collection of things.  The problem is timeWhen makes the asynchronous nature of observables explicitly apparent.  You have no idea if it will ever actually become a collection; e.g., maybe the mouse is never clicked.

    And as Andreas also pointed out, an event might only be meant to occur once.  This is actually more evident in things like an asynchronous web request - you know there will only be one response, so why should the observable member be called, Responses?  Or should it just be called Response?  Now we have also lost consistency.  If we were to call it, WhenResponseArrived instead then it remains consistent and clear.

    The reason why my variable names were nouns is simply because if they are used in a query it's going to be in terms of their properties as an occurrence of the event.  Later in the query we can already assume that the event already occurred, as opposed to a member that offers the possibility of an event occurring.

       var q1 = button.WhenClicked.Select(click => click.EventArgs.Button);

       var q2 = clicks.Select(click => click.EventArgs.Button);

    The asynchronous nature of q1 is clear, whereas it is lost in q2.  Without looking at the types, you might as well assume that clicks is an IList<IEvent<MouseButtonEventArgs>>.

    - Dave
    http://davesexton.com/blog
    Wednesday, January 13, 2010 1:57 PM
  • Hi, 

    Here, I think I can formalize the naming conventions that I'll be using from now on unless somebody comes up with something better:

    1. Use a When prefix on all members that return IObservable<T>. This will reveal their asynchronous and composable nature.
    2. Use third-person present form if it comes naturally.
    3. If third-person does not come naturally, use past tense if it comes naturally.
    4. If past tense does not come naturally, fall back to first-person present tense.

    Good
    Examples:

    Rule 2: WhenMouseMoves     (Better than WhenMouseMoved in terms of continuations; e.g., when the mouse moves, do this...)
    Rule 3: WhenClicked             (Better than WhenClick)
    Rule 4: WhenMouseDown      (Not much of a choice here :)

    Bad Examples:

    Rule 1: MouseMoves             (Is it asynchronous? Is it a cached list?)
    Rule 2: WhenMouseMove       (Improper English.  If there's a MouseMove event, name its observable counterpart WhenMouseMoves.)
    Rule 3: WhenClicking            (Interesting, but not as nice as WhenClicked.  Also uses pluralization, which is wrong if you expect only one click.)

    - Dave
    Wednesday, January 13, 2010 3:03 PM
  • The issue with using the special When prefix for an asynchronous thing is that you should then use the same naming scheme for other asynchronous things.  So events should be prefixed too because they are asynchronous and may or may not be fired, however the Framework Design Guidelines advises against this. I think this is also an argument for a type of Hungarian notation where the variable name describes the type and this is also deprecated these days (at least in the .NET world).
    Thursday, January 14, 2010 9:12 AM
  • Hi,

    > The issue with using the special When prefix for an asynchronous thing is that
    > you should then use the same naming scheme for other asynchronous things.  So events should be prefixed too


    Events and IObservable are clearly not the same thing.  I'd prefer if C# had some sugar that allowed us to treat events as IObservable, but that doesn't exist now.  When will differentiate between them.

    Also, you're free to create an IObservable property or method that doesn't have any corresponding event.  In this case I still prefer using a When prefix.  All of my former reasons apply, and in addition we must consider that we may want to add an event in the future, in which case we'd want to reserve the recommended event-naming scheme for the event and not use it for our IObservable.  This is also true for non-event members.  For example, I may want to add a property to my Canvas class in the future that returns a buffered list of move moves.  Perhaps the most appropriate name for this property would be MouseMoves.  WhenMouseMoves will differentiate between the IObservable of points and the buffered list of points.

    > events should be prefixed too because they are asynchronous and may or may not be fired [snip]

    Events are not composable.  You have to register handlers (callbacks).  IObservables are composable.  Using a When prefix for observable members implies that continuations will be executed for each observed element; When provides a nice readable flow when used to compose a query; e.g.,   button.WhenMouseMoves.Select(...).  You cannot do this with events.  This would be silly: button.WhenMouseMove += new EventHandler...

    > I think this is also an argument for a type of Hungarian notation where the variable name describes the type and
    > this is also deprecated these days (at least in the .NET world).


    Hungarian notation is not meant to describe the type (it's a common misconception).  It's meant to describe the semantics.  Also, the notation usually consists of a single lowercase character.  I can see what you mean, but it's a stretch.  When does imply both the type and its semantics.

    But When is simply a prefix, in the same way that the Framework Design Guidelines recommend that we use On[EventName] in all of our event-raising methods.  (http://msdn.microsoft.com/en-us/library/ms229011(VS.100).aspx)

    - Dave
    http://davesexton.com/blog
    Thursday, January 14, 2010 9:43 AM
  • Count me as another vote for the plural property form.

    Examples: KeyUps, KeyDowns, PropertyChanges, MouseMovements
    Thursday, January 14, 2010 8:06 PM
  • Hi,

    Pluralization can be tricky.  It wouldn't make for much of a "standard".  For example:

    class Person
    {
      // Talks is actually the singular form of the verb, believe it 
      // or not, in the same way as Up, Down and Move are singular.
      void OnTalks(EventArgs e) { ... }
      event EventHandler Talks;
    
      // hmm... Talk is the plural form, but that doesn't seem right - it's no longer 
      // describing a "collection of things", as was mentioned above by Rich257.
      IObservable<IEvent<EventArgs>> Talk { get; }
    
      // Happiness :D
      IObservable<IEvent<EventArgs>> WhenTalks { get; }
    }

    - Dave
    Thursday, January 14, 2010 9:44 PM
  • The concept of Rx seems to be to (i) make events first class objects, and to (ii) describe a stream of asynchronous data.  Perhaps the lack of concensus so far is because of these different concepts.

    In the Person example above, it seems that the IObservable is simply providing the event as a property, concept (i).  In other examples the interesting thing is the data of the event (or a transformation of it), which is more like a collection, which is concept (ii).

    In the Person example, the talk events have no data with them so they aren't a stream of data, they are a stream of notifications.  If the code that responds to the event stream then fetches some data from the object that raised the event, perhaps a data stream should be visible rather than a stream of events.

    As ever, naming is always a hot topic!

    Friday, January 15, 2010 9:30 AM
  • Hi,

    > In the Person example, the talk events have no data with them so they aren't a stream of data, they are a stream of notifications.

    Data is information.  Notifications aren't information?

    Furthermore, observables are maybe-streams of data since the event might never be raised, or perhaps only raised once.  Let's not forget the time component, which is implied by When yet lost in pluralization.

    > If the code that responds to the event stream then fetches some data from the object that raised the event, perhaps a data stream
    > should be visible rather than a stream of events.


    Perhaps.  What you're describing is a projection (which you mentioned before as "transformation").  What you're assuming is that the sender isn't important to the observer.  I think this depends upon the likely use cases of the observable - but I'm not sure it has anything to do with naming conventions.

    > As ever, naming is always a hot topic!

    Agreed :D

    - Dave
    http://davesexton.com/blog
    Friday, January 15, 2010 11:14 AM
  • Hi,

    Let's formalize the pluralization rules for naming observables as a comparison to my formalized rules for using the When prefix.

    Pluralization

    1. Use pluralization on all members that return IObservable<T> and may produce more than one value.
    2. If pluralization doesn't come naturally when promoting an event member, then you're on your own.  Perhaps find a different word and tie them together via documentation.
    3. Use singular form on all members that return IObservable<T> and may produce at most one value.
    4. If singular form collides with an existing member, such as when promoting an existing event, then just use pluralization anyway.
    5. When adding a new member to a type that already has an observable member with a name based on these conventions, choose a different name for the new member even if it's not ideal, or rename the observable member unless it's a major breaking change.


    When Prefix (copied from above)

    1. Use a When prefix on all members that return IObservable<T>. This will reveal their asynchronous and composable nature.
    2. Use third-person present form if it comes naturally.
    3. If third-person does not come naturally, use past tense if it comes naturally.
    4. If past tense does not come naturally, fall back to first-person present tense.


    - Dave


    http://davesexton.com/blog
    • Edited by Dave Sexton Friday, January 15, 2010 11:35 AM Added missing word: name
    Friday, January 15, 2010 11:33 AM
  • =) May be its time to ask this again. Have anybody discover more naming sachems?
    Saturday, March 06, 2010 11:32 AM
  • Hi everyone,

    Here's a new related post on naming conventions that extends the idea to choosing names based on the kind of observable.

    Dual Purpose of Observables
    http://social.msdn.microsoft.com/Forums/en/rx/thread/0d147887-eda9-4a74-b8b3-7fc93f44b417

    - Dave


    http://davesexton.com/blog
    Thursday, April 29, 2010 6:47 PM
  • The difference with events is that they use a different syntax when subscribing and unsubscribing so it is more clear due to the += and -+ operators. With observables it seems less clear so especially with the overlapping of other Linq extension methods for IEnumerable and IQueryable.

    I'm currently leaning towards the When prefix although I came to this post for guidance and haven't made up my mind yet.

    Thursday, September 19, 2013 6:56 PM
  • I have some viewmodels that need properties for databinding, but my viewmodel code wants to do stuff with IObservable data on those properties. So at first I was looking a solution like...

    public interface IPerson : INotifyPropertyChanged {
       string FirstName {get; set; }
       IObservable<string> WhenFirstName {get;}
       string LastName {get; set; }
       IObservable<string> WhenLastName {get;}
    }

    But as you can see this gets quite ugly. Instead I'm probably going do this...

    interface IProperty<T> : INotifyPropertyChanged, IObservable<T> {
       T Value {get;set;}
    }
    
    interface IPerson {
       IProperty<string> FirstName {get;}
       IProperty<string> LastName {get;}
    }


    So in other words, each property exposes both an observable and a current value. This looks quite clean to me. My other thought was that this observable stuff is so useful that if we're going to create a naming scheme, we should use the most simple name for the observable and the more clunky name for the regular property, like this...

    public class Person {
       public string FirstNameNow {get; set;}
       public IObservable<string> FirstName {get;}
    }

    Other flavors of this are to call the non-observable something like FirstNameProperty or FirstNameValue.

    In general, if there are going to be two different properties, one for the observable and one for the simple property, I prefer when their names start the same and use a different suffix.

    Wednesday, June 29, 2016 6:44 PM