Phillip Trelford's Array

POKE 36879,255

Declarative Naming

Like sentence construction, declarative programming requires careful selection of words. Nouns for class and property names, verbs for method and event names.

Ignoring the arbitrary ‘I’ at the start of interface names, nouns or adjectives can describe their capabilities, e.g. comparable, equatable and observable.

Declarative names should describe the “what” without the “how”. Short names typically indicate good abstraction. Long or schizophrenic names are a code smell suggesting poor separation of concerns and that refactoring may be required.

Luke“ Luke. Let the force words guide you.”

A Brief History of Naming

In the beginning, Microsoft operating systems such as MS-DOS or Windows 3.x did not support long file names like other operating systems such as Unix, OS/2, and the Apple Macintosh MAC OS. The earlier versions of Microsoft's operating systems had a limitation of an eight character file name or directory, and a three character extension. [Information about long file names]

Going back a bit further to the 8-bit era of computing, I remember my first Z80 assembler for the Amstrad CPC, HiSoft’s DevPac which only treated the first 6 characters of a label as significant. Meaning coding schemes for labels were required for larger programs, a bit like postal codes for addresses, .

Later with newer assemblers, CPUs and C, restrictions relaxed, but naming conventions like Hungarian notation remained to indicate things like the types of variables. Thankfully with the advent of modern compilers and IDEs, bringing type checking and type information on tooltips, the need for these notations has been removed. Nowadays we should be free to focus on good declarative naming.

Declarative Naming Resources

When following a variant of Domain-driven design (DDD), a ubiquitous language helps define names for core business concepts. This just leaves naming for technical abstractions, and there are plenty of resources out there to help.

Online:

Books:

And now for some examples…

Managers

Like a manager typically has no specific role, so a manager class is probably a poor abstraction. More often than not you’d be better starting with a collection.

INotifyPropertyChanged

In an MSDN article by Josh Smith on MVVM, a ViewModelBase class is suggested that implements the INotifyPropertyChanged interface. To me this seems a poor abstraction as a class need not be a View Model in order to implement this interface, and the name gives no obvious indication to its behaviour, instead suggesting a set of base behaviours. A better abstraction would be ObservableObject, like the framework’s ObservableCollection class which implements the not too dissimilar INotifyCollectionChanged interface.

IDictionary

An improvement on the naming of the pre-generics un-typed equivalent Hashtable class, the Dictionary class better specifies the “what” over the “how”. However the new underlying generic IDictionary interface could be improved by separating the concerns of reading and writing items across 2 interfaces.

GetOrAdd

The new ConcurrentDictionary class in .Net 4.0 contains a method GetOrAdd. Again in terms of naming, this seems to be a poor abstraction, and again by emphasizing the “how” rather than the “what”. A better name would be Obtain, a suggestion in a Martin Fowler tweet.

ToString

A good example of declarative naming, also promoting the idea of functional transformation and idempotence.

Pluralisation

I like pluralisation for collections, e.g. Items, its both short and descriptive. The new IObservable<T> interface as used by the Reactive Extensions (Rx) also seems to lend itself well to pluralisation, e.g. Notifications.

Last word?

For variable names the last word of the object may suffice, e.g.

let connection = new SqlConnection()

Finally

KentBeck: if you can’t find a really good name for something, pick a really terrible name (i like "fred"). then you are motivated to fix it.

Disclaimer:

For legacy code consistency may be as important as declarative naming, so abandoning coding schemes like Hungarian notation on a large codebase may be counter-productive.

Pingbacks and trackbacks (1)+

Comments are closed