Naming - Content Semantics

[Paolo F Cantoni]

Apart from the normal organisational reasons for having naming standards, we also want to enforce the relevant semantics between the name of the element and its contents.  This aspect is vital in the creation of programs that perform reliably, can be more easily understood and maintained.  If the name of the element does not convey its content then the program cannot be understood easily.

[size=13]“Names are the heart of programming.  In the past people believed knowing someone's true name gave them magical power over that person.  If you can think up the true name for something, you give yourself, and the people coming after, power over the code.  Don't laugh!

A name is the result of a long deep thought process about the ecology it lives in.  Only a programmer who understands the system as a whole can create a name that "fits" with the system. If the name is appropriate, everything fits together naturally, relationships are clear, meaning is derivable, and reasoning from common human expectations works as expected.”[/size] – Todd Hoff ([email protected], http://www.possibility.com/Tmh)

[size=24]UpholdContentSemantics[/size]
[size=16]Context:[/size]
[size=13]You need to choose a name for an element[/size]
[size=16]Issue(s):[/size]
[size=13]

• Names that don't reflect the content make for confusion
  
• Similar elements should have similar names
  
• Elements in the same dimension should so indicate
  

[/font][/size][/color]
[size=16]Force(s):[/size]
[size=13]

• Names that do reflect the content may be hard to type manually (likely to be long)
  
• Short names (especially abbreviations) are unlikely to reflect the content
  

[/font][/size][/color]
[size=16]Therefore:[/size]
[size=13]Devise names that uphold the content semantics[/size]
[size=16]Example(s):[/size]
[size=13]DriverShiftEpisode, TEMPORARY_DATABASE_PREFIX, TableHasAlreadyBeenGenerated, camel_cased_logical_table_persistence_caption[/size]
[size=16]Discussion:[/size]
[size=13]When an element has good content semantics, the name of the element accurately conveys important information about its data content.  For example, if the element contains the count of the items in a list, then we know that the data within the element should be a non-negative integer – however it is implemented.  If we implement this element as a string, for example, then the string must always contain a non-negative integer.  In addition, if we need to perform arithmetic on this element, the process must conform to the rules of integer arithmetic.  We can thus define the semantics of a “count” element.  All such count elements have the same semantics.  We describe count as a dimension.  Each such dimension can have the appropriate semantics and constraints defined for it, in addition to its notional abstract data type.  This information can be retained in a formal lexicon.  If we include the dimension name as part of the element name, we are imparting a significant amount of information as to the contents of the element and the operations that can legitimately be performed on it.[/size]

[size=0]©2006 Paolo Cantoni, -Semantica-[/size]

[mikewhit]

One of my university supervisors, Martin Richards [http://www.cl.cam.ac.uk/~mr/], said during a lecture that one of the most difficult things in programming was thinking of good names for variables/functions.

How right he was !

[KP]

• Similar elements should have similar names

Especially important with domain terminology. Does your project refer to Customers, Clients, Purchasers, Buyers or what? Pick one, document your choice, and stick with it.

[KP]

If the name of the element does not convey its content then the program cannot be understood easily.

The most basic of basic advice, but doesn't hurt to get it written down:

• Name variables, attributes, properties etc as Nouns or noun phrases.
  
• Name procedures, methods, subroutines etc as Verbs or verb phrases.
  
• Name booleans (variables or functions) as Questions that yield a yes/no answer.

[AshK]

co-incidently I encountered this yesterday, titled "I shall call it.. SomethingManager":

http://www.codinghorror.com/blog/archives/000553.html

[sargasso]

Name booleans (variables or functions) as Questions that yield a yes/no answer.

and make sure the answer reflects the question....

if value of IsFalse is true then IsFalse should return true which makes it semantic gibberish...

b

On reflection, I'm being cryptic.  I have seen a significant cost incurred in a dev project where the semantics of the questions did not match the values.  The "IsFalse" example is trite, the actual examples were much more obtuse.

[Paolo F Cantoni]

The question of booleans is interesting.

A boolean is often used as a return value to denote the success or failure of a method.  If we were not interested in the processing result, the method would normally have have a void (or null) result.

I have now come to the view that this is an inappropriate use of the boolean, for a number of reasons (which I hope to elucidate in separate pattern when I've got my thoughts together).

However, the reason I'm talking about it here is that I believe there are naming implications for the method depending upon what is intended.

If the objective of the method is to deliver a boolean result such that it can be assigned to a LValue (that is, we are NOT returning the processing status), then it should follow the naming rules for a boolean variable or property.  The naming rules should be such that the name is that of a fact (and thus in the passive voice):  TaggedValueWasFoundInElement(Tag, Element),  .IsValidForPeriod(Commencement, Termination).  Naturally, this would allow it to be used directly in the if statement conditional, without further effort:
If TaggedValueWasFoundInElement(NameTag, Element) Then
   'Process Tag value
End If

if (!Cheque.IsValidForPeriod(Commencement, Termination))
{
   //Bounce it...
}

I use a different process to handle processing results.  I use a HResult concept to provide more information regarding the processing.  If I need to take appropriate action I can test to the required level.  I provide wrappers such as bool SUCCEEDED(HResult), bool FAILED(HResult) etc.  This allows me to implement multi-state logic very easily.  The method is named using an active (verb based) name - such as: FindUDXMLStructure(string  name), SetLogicalOnlyInferenceOnEntity(value As Boolean)

Thoughts?

Paolo

[Hans]

Hi Paolo,
I follow you in most parts. The part where I diverge has been unmentioned sofar:
A name should also be *simple*.
I agree e.g. in the semantics of "count" as a very good name for what it's doing. However, given that, I wouldn't ever change it (by pre- or suffixing it).
Instead, in a class "Orders" "count" will count the orders, in "ShoeRetails" the same "count" will do the 'same' for shoes.

My Greetings to Italy from Germany,
Hans

[Hans]

..sorry: I forgot to mention HResult and other Com-antiquities we still suffer from:
I personally keep them wrapped silently (i.e. privately) within a class, from which I throw my exceptions.

That shields others from digging into medeaval ages.

Cheers
Hans

[Paolo F Cantoni]

Hi Paolo,
I follow you in most parts. The part where I diverge has been unmentioned so far:
A name should also be *simple*.

I use the Einstein's dictum:  "Keep things as simple as possible, but no simpler."  Often, simple solutions become simplistic because we simplify too far.  This is what Einstein is warning about.

I agree e.g. in the semantics of "count" as a very good name for what it's doing. However, given that, I wouldn't ever change it (by pre- or suffixing it).

I am (temporarily) making an assumption - which I'm asking you to clarify (see other post)  that here you are talking about qualifiers and not adornments.  In the pattern on adornments, I stress that adornments must not replace any significant semantics that should be in the name itself.

Instead, in a class "Orders" "count" will count the orders, in "ShoeRetails" the same "count" will do the 'same' for shoes.

Here you mean:  Order.Count  or do you mean a collection class Orders.Count?  I agree that where the language supports Class and Object semantics, then (unqualified) Count is appropriate.  However, if I take that count and use it in a local variable, then I must call that variable OrdersCount.  That is, I must qualify it.  Similarly, if I have (or add) another property: Orders.LargeOrdersCount I can no longer retain a simple Orders.Count, I now have to rename it Orders.TotalOrdersCount as Orders.Count is no longer sufficiently semantically unambiguous.

Does this violate your simple principle?

Paolo

BTW: I'm not in Italy, but downunder in Australia.  

[Hans]

Hi Paolo,

  as to Italy: I sometimes run into mistakes ;-)
As to count in class Orders, it is Orders.count.

I am not a missionary in ultimate naming principles myself, just a victim of silly rules in my company for which a majority voted.
E.g: The db folks objected the liberal namings in stored procedures hempering their work and the underscores annoyable to write. They thought: If the table names which the SPs use were given as a prefix, things would appear in order and harmony.
However, these SPs for most part don't belong to the db, but to application layers that the db folks are incapable to write nor even to maintain! Things will worsen by that silly convention, as noone will be able to tell what the SP code will be actually doing when a table name changes and if that SP actually will be obsolete.

Another example: You qualify the counter further, for instance into prefixing longCounter, since a type is a long. A developer may be conformant to that rule, but he may right away misuse the word counter for something different, for instance an address. That's what I personally would object against! I mean: when names obscure or even mislead the *real* meaning of the type in its very context, that is what is bad. Other adornments are simply superfluous.

Regards
Hans
(We're really having spring over here! Yeah! We all felt winter would never end this year..)

[Paolo F Cantoni]

Hi Paolo,

   as to Italy: I sometimes run into mistakes ;-)
As to count in class Orders, it is Orders.count.

I am not a missionary in ultimate naming principles myself, just a victim of silly rules in my company for which a majority voted.

Ah... yes... the majority vote!  Of all the naming standards I've seen, the worst were majority votes.

E.g: The db folks objected the liberal namings in stored procedures hampering their work and the underscores annoyable to write. They thought: If the table names which the SPs use were given as a prefix, things would appear in order and harmony.
However, these SPs for most part don't belong to the db, but to application layers that the db folks are incapable to write nor even to maintain! Things will worsen by that silly convention, as no one will be able to tell what the SP code will be actually doing when a table name changes and if that SP actually will be obsolete.

I thought that was why... What can I say???

Another example: You qualify the counter further, for instance into prefixing longCounter, since a type is a long. A developer may be conformant to that rule, but he may right away misuse the word counter for something different, for instance an address. That's what I personally would object against! I mean: when names obscure or even mislead the *real* meaning of the type in its very context, that is what is bad. Other adornments are simply superfluous.

No, I don't qualify with types.  I (conditionally) adorn with type symbols and then these are abstract datatypes, not actual datatypes (thus iCounter - an Integral {as opposed to Real or Boolean)).  

Using a counter for an address is not misuse it's abuse! :-)

Paolo