Naming Notifications

Often when you invoke a method on an object, you expect something to happen. The object will do something to itself or return some other object to you. Because of this, many method names start with an imperative -- add , cancel, verify etc; but there is at least one other class of methods: methods which are used to notify an object about some event. How do we name these methods?

One convention is to use the name of the event as the method name. Using this convention, you end up with names like activityComplete and indicatorOn.

This naming convention is nice, but sometimes it is confusing. Does indicatorOn turn an indicator on, or does it notify an object that an indicator is on?

When time behaves normally, events happen prior to their reporting. For this reason, a better convention is to name notification methods in the past tense, for example, activityCompleted and indicatorSignaled.

Anyone else HaveThisPattern?

-- MichaelFeathers

Yes, and we also name our notifications in the past tense which reconciliates both ideas, as in notification: activityDidCompleteNotification, method : activityDidComplete.

Of course, this all leads to the question: why isn't there an indicator object that you tell beSignaled? The indicator can then tell other objects what they need to know in terms that are appropriate to them.

The sender of the notification is outside of the scope of the discussion. It might even be a wrapper for some sensor that is not signalled from another part of the program, but from the system. Anyway, we HaveThisPattern. We also have the convention to name methods that respond to events coming from outside the system (the user) "handleX()". Notifications that come from other parts of the system are named after the above convention. (Example: "handleSelectionChanged" vs. "selectionChanged()"

In my first life as a hardware systems engineer, 25 years ago when DigitalEquipmentCorporation was new and exciting, we needed to resolve this same question regarding bits in device registers and interfaces: for a given bit (let's use "Interrupt Request" as an example), how do I distinguish between its two states and between the actions that change its state?

The convention we adopted was to use the past tense as suggested here (the name of the boolean would be "InterruptRequested?"), use the terms "Asserted" and "Negated" to refer to its state, and use the verbs "Assert" and "Negate" to refer to changing its state.

I think the combination of these conventions works well. I prefer "activityCompletedNotification" to "activityDidCompleteNotification", and I prefer "activityCompleted" to "activityDidComplete".

But we also have notifications about things to come: activityWillStartNotification and activityWillStart. Using did for the past makes the convention a bit more consistent and obvious. --MarcoScheurer

To finish the above example, my own convention would be:

activityCompleted "Answer the state of the activityCompleted notification"

activityCompletedAssert "Signal the activityCompleted notification"

activityCompletedAsserted "Handle the signaling of the activityCompleted notification"

By the way, I suspect this is closely related to WhenAndWhile.

--TomStambaugh

Tom, were you ever tempted to make the first one: isActivityCompleted so that it reads like a query? -- MichaelFeathers

Yes, and standing on its own, I much prefer it, because it more clearly reflects its semantics. In practice, however, I quickly found (as with all prefex rules) that its use with, say, a dozen notifiers causes me to see, in the message pane of my browser, a glob of methods that all begin with "is...". This is almost NEVER how I want to use them...I generally want to see all the methods pertaining to a given event at the same time.

In a perfect world, my browser will be smarter...and then I probably will revert to the "isActivityCompleted" form.

--TomStambaugh

Why not use "notify" or "fire" as the prefix?

isActivityCompleted notifyActivityCompleted

isIndictorSignaled notifyIndicatorSignaled

And so on. --RobertDiFalco

I sometimes use the prefix 'on'. As in onComplete, or onNotified. This works best for UI events (like onPressed, or onSelect), but also seems fine for other types of notifications.

I tend to do this as well. I use "fire" to send the notifications and "on" to process them. Of course, I always have on delegate to methods with IntentionRevealingNames. --RobertDiFalco

I HaveThisPattern - I've started naming functions that return boolean values after the expected condition when they are returning TRUE, like:

 isTheLightOn() { if self.lightIsOn return TRUE else return FALSE }

-- PeteHardie

If the purpose of the naming is to tag a response that is to "do" something and the message query will return a boolean yes or no, why not have names indicated what is done when as in:

if activityCompleted do stuffUntilDone endif report time,stuffCompleted

or possibly:

while notifyIndicatorSignaled startOtherStuff report time,otherStuffStarted endWhile stopOtherStuff report time,otherStuffStopped

or, to allow the otherStuff to be completed before stopping it:

 while notifyIndicatorSignaled
   doOtherStuff
   report time,otherStuffUnderway
 endWhile
 if otherStuffDone 
   report time,otherStuffDone
 else
   finishOtherStuff
 endif

Hmm. If one is polling for current status of non-interrupting actions one uses the IsActionComplete() naming form, eh? For interrupt responses one can use the Visual Basic/Javascript/Whatever construct of OnStimulus() naming for those methods. Signal names would be things like ActionUnderWay or ProcessnamePending or some such. I find it pretty easy to come up with good names for my embedded hardware stuff by sticking to a few conventions like these.

Of course, before any naming of entities can ever begin you need a glossary of terms so that everybody knows what you're talking about. That way there will be no confusion between the noun and verb forms of certain terms, etc. Get that right up front and Bob's yer uncle when you name actions. -- MartySchrader

CategoryCodingConventions, CategoryCodingIssues, CategoryNaming