Events - naming convention and style

Question

I'm learning about Events / Delegates in C#. Could I ask your opinion on the naming/coding style I've chosen (taken from the Head First C# book)?

Am teaching a friend about this tomorrow, and am trying to come up with the most elegant way of explaining the concepts. (thought the best way to understand a subject is to try and teach it!)

class Program
    {
        static void Main()
        {
            // setup the metronome and make sure the EventHandler delegate is ready
            Metronome metronome = new Metronome();

            // wires up the metronome_Tick method to the EventHandler delegate
            Listener listener = new Listener(metronome);
            metronome.OnTick();
        }
    }

---

public class Metronome
    {
        // a delegate
        // so every time Tick is called, the runtime calls another method
        // in this case Listener.metronome_Tick
        public event EventHandler Tick;

        public void OnTick()
        {
            while (true)
            {
                Thread.Sleep(2000);
                // because using EventHandler delegate, need to include the sending object and eventargs 
                // although we are not using them
                Tick(this, EventArgs.Empty);
            }
        }
    }

---

public class Listener
    {
        public Listener(Metronome metronome)
        {
            metronome.Tick += new EventHandler(metronome_Tick);
        }

        private void metronome_Tick(object sender, EventArgs e)
        {
            Console.WriteLine("Heard it");
        }
    }

n.b. Code is refactored from http://www.codeproject.com/KB/cs/simplesteventexample.aspx

Answer 1

Looks good, aside from the fact that OnTick doesn't follow the typical event invocation model. Typically, On[EventName] raises the event a single time, like

protected virtual void OnTick(EventArgs e)
{
    if(Tick != null) Tick(this, e);
}

Consider creating this method, and renaming your existing "OnTick" method to "StartTick", and instead of invoking Tick directly from StartTick, call OnTick(EventArgs.Empty) from the StartTick method.

Answer 2

Interesting how Microsoft seems to break its own naming conventions with Visual Studio generated event handler names.

See: Event Naming Guidelines (.NET Framework 1.1)

Answer 3

A point I have found after using events in .Net for many years is the repetitive need to check the event for a null handler on every invocation. I'm yet to see a piece of live code that does anything but not call the event if it is null.

What I have started doing is to put a dummy handler on every event I create to save the need to do the null check.

public class Metronome
{
    public event EventHandler Tick =+ (s,e) => {};

    protected virtual void OnTick(EventArgs e)
    {
        Tick(this, e);  // now it's safe to call without the null check.
    }
}

Answer 4

In your case it could be:

class Metronome {
  event Action Ticked;

  internalMethod() {
    // bla bla
    Ticked();
  }
}

---

Above sampple use below convention, self-describing ;]

Events source:

class Door {

  // case1: property change, pattern: xxxChanged
  public event Action<bool> LockStateChanged;

  // case2: pure action, pattern: "past verb"
  public event Action<bool> Opened;

  internalMethodGeneratingEvents() {
    // bla bla ...

    Opened(true);
    LockStateChanged(false);
  }

}

BTW. keyword event is optional but enables distinguishing 'events' from 'callbacks'

Events listener:

class AlarmManager {

  // pattern: NotifyXxx
  public NotifyLockStateChanged(bool state) {
    // ...
  }

  // pattern: [as above]      
  public NotifyOpened(bool opened) {
  // OR
  public NotifyDoorOpened(bool opened) {
    // ...
  }

}

And binding [code looks human friendly]

door.LockStateChanged += alarmManager.NotifyLockStateChanged;
door.Moved += alarmManager.NotifyDoorOpened;

Even manually sending events is "human readable".

alarmManager.NotifyDoorOpened(true);

Sometimes more expressive can be "verb + ing"

dataGenerator.DataWaiting += dataGenerator.NotifyDataWaiting;

Whichever convention you choose, be consistent with it.

Answer 5

I would say the best guide to events in general, including naming conventions, is here.

It is the convention I have adopted, briefly:

• Events names are typically terminated with a verb ending with -ing or -ed (Closing/Closed, Loading/Loaded)
• The class which declares the event should have a protected virtual On[EventName] which should be used by the rest of the class for raising the event. This method can be also used by subclasses to raise the event, and also overloaded to modify the event-raising logic.
• There is often confusion about the use of 'Handler' - for coherence, all delegates should be postfixed with Handler, try to avoid calling the methods which implement the Handler 'handlers'
• The default VS naming convention for the method which implements the handler is EventPublisherName_EventName.

Answer 6

Microsoft has actually written extensive set of naming guidelines and put it in the MSDN library. You can find the articles here: Guidelines for Names

Aside from the general capitalization guidelines, here is what it has for 'Events' on the page Names of Type Members:

Do name events with a verb or a verb phrase.

Do give event names a concept of before and after, using the present and past tense. For example, a close event that is raised before a window is closed would be called Closing and one that is raised after the window is closed would be called Closed.

Do not use Before or After prefixes or suffixes to indicate pre and post events.

Do name event handlers (delegates used as types of events) with the EventHandler suffix.

Do use two parameters named sender and e in event handler signatures.

The sender parameter should be of type Object, and the e parameter should be an instance of or inherit from EventArgs.

Do name event argument classes with the EventArgs suffix.