Naming - Adornments

[Paolo F Cantoni]

[size=24]AdornToReduceErrors[/size]
[size=16]Context:[/size]
[size=13]You need to use named elements correctly.[/size]
[size=16]Issue(s):[/size]
[size=13]Various factors often contribute to errors in writing code.  Often these are picked up by the language processor, but often they aren't.  Some of these are:

• Scoping (coding block)
  
• Visibility (Public ... Private)
  
• Datatype (Integer, String, Real, Boolean...)
  
• Volatility (Constant, variable, WORM)
  
• Nature (atomic element versus structure)
  

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

• limited range of mechanisms to indicate these issues
  

[/font][/size][/color]
[size=16]Therefore:[/size]
[size=13]Adorn the basic name to reduce errors[/size]
[size=16]Example(s):[/size]
[size=13]gsSECTION_NAME        (global string constant Section Name)
moAncestorClassifier        (private member object reference to Ancestor Classifier)
IsEmpty        (public boolean property indicating the instance is empty)
validateSubTypeCluster        (private method to validate a subtype cluster)
SetLogicalOnlyInferenceOnEntity        (public method)
s_camel_cased_logical_table_persistence_caption         (local string WORM variable containing the camel cased caption to be used for this logical table)
[/size]
[size=16]Discussion:[/size]
[size=13]My experience has been that with the kinds of adornments I use, I actually reduce the number of errors I make in coding.  The form of the name tells you a lot about where it can be used (LV versus RV), where it came from, what it looks like or how it can be cast.  Also, the adornments allow the same conceptual thing, rendered differently to have the same semantic name, but be differently adorned.  I find this capability to be most useful.

Finally, language processors often can't process hardcopy very well...   [/size]

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

[SF_lt]

one thing: LV and RV stands for something left and right?  

[Paolo F Cantoni]

one thing: LV and RV stands for something left and right?  

Yes...

LV is short for LValue and RV correspondingly.

LValue:
<programming> A reference to a location, an expression which
can appear as the destination of an assignment operator
indicating where a value should be stored. For example, a
variable or an array element are lvalues but the constant 42
and the expression i+1 are not. A constant string may or may
not be an lvalue (it usually is in {C}).

(1995-04-28)

Source: The Free On-line Dictionary of Computing, © 1993-2005 Denis Howe

HTH,
Paolo

[TrtnJohn]

While I understand and agree that adornments are useful, I don't always like them because:

1)  Lack of consistent standards.  If adornments are so good I really believe there should be global standards enforced by the compiler.

2)  Readability.  Adornments can cause the code to start to look less like plain spoken English and more like gobbly-gook only understood by the author.  (See comment 1).

Because of this I like to minimize my usage of adornments myself.  When I code, I typically try and expose every data element as interface elements in my classes.  I don't want to burden these names with adornment rules because the name itself should communicate exact meaning to a client of the class.

[jeshaw2]

This looks like an object oriented version of the old Hungarian notation.

[Paolo F Cantoni]

This looks like an object oriented version of the old Hungarian notation.

Looks can be deceiving...  

Yes, there are elements of Simonyi's Hungarian notation.  I actually bothered to read the original paper.  One interesting feature is that Charles Simonyi decreed was that the datatype should be the abstract datatype.  This appears to observed "more in the breach"!

Also, if you look at all the public examples in the original pattern, they are almost all unadorned.

So, in my view, it is sufficiently distinct from Hungarian notation to not be tagged as such...

The examples I give are from my naming architecture; but, as I previously said, each team should decide what their needs are, document them, and then compare any naming architecture proposal with the stated requirements.

Paolo

[Paolo F Cantoni]

While I understand and agree that adornments are useful, I don't always like them because:

1)  Lack of consistent standards.  If adornments are so good I really believe there should be global standards enforced by the compiler.

Adornments, as you suggest, shouldn't take the place of semantically valid names.  I don't think there can be universal standards.  
Some adornments are like additional metadata about the element.  My preference would be to formalise these metadata similar to .NET attributes and then let the compiler or runtime use this information to locate errors.

2)  Readability.  Adornments can cause the code to start to look less like plain spoken English and more like gobbly-gook only understood by the author.  (See comment 1).

While, technically this is true, when you use adornments in a consistent fashion, you become "blind" to them.

Because of this I like to minimize my usage of adornments myself.  When I code, I typically try and expose every data element as interface elements in my classes.  I don't want to burden these names with adornment rules because the name itself should communicate exact meaning to a client of the class.

In my naming architecture, the use of adornments is not universal (but, I hope, consistent).  They are used within methods and attributes.  As with your point here, publicly visible elements are essentially unadorned.

Paolo

[sargasso]

...there should be global standards enforced by the compiler.

I reckon they should be global facilities provided by the IDE.  (Sort of like a certain modelling tool... )

We now accept and deliver requirements for end user systems that provide useability features to make their lives easier.  My beef is that we put up with this entire problem when we should be complaining to the IDE deliverers to come up with a workable solution.

bruce

(P.S. I'm not having a go at this thread tho!)

[Paolo F Cantoni]

I reckon they should be global facilities provided by the IDE.  (Sort of like a certain modelling tool... )

We now accept and deliver requirements for end user systems that provide useability features to make their lives easier.  My beef is that we put up with this entire problem when we should be complaining to the IDE deliverers to come up with a workable solution.

bruce

(P.S. I'm not having a go at this thread tho!)

Yes!

Paolo

[Hans]

Personally, I think, that goes a bit too far: Although I am withh you that consistent naming is the decisive measure for good domain modeling and thus for the rest of the application, it is domain driven.
Hungarian notation itself is not a good strategy. The same holds for any table centric naming convention for stored procedures (within the database).

Regards
Hans

[Paolo F Cantoni]

Hi Hans,
Welcome...

Personally, I think, that goes a bit too far:

It's not clear to me what you are referring to here.  The pattern or some of the subsequent discussion.

Although I am with you that consistent naming is the decisive measure for good domain modeling and thus for the rest of the application, it is domain driven.

This should be obvious, but apparently it isn't.  I still find I have to argue this.

Hungarian notation itself is not a good strategy.

Why is Hungarian not a good strategy?  As I mention, I don't use it, but do use elements of it.  I know why I don't use it, but as I mentioned when I started this series of threads, I'm interested in why others do and say what they do.  Can you elaborate on WHY you see Hungarian notation as not a good strategy.

The same holds for any table centric naming convention for stored procedures (within the database).

Can you elaborate further what you mean here.  I have an inkling, but as I'm said else where, I prefer not to make any assumptions whenever I can.

Paolo

[Hans]

Hi Paolo,
there is certainly much personal taste in naming strategies.
Sure, nothing is wrong to a certain style.
Personally, I make a distinction between local and nonlocal variables, avoid any prefixes. (I admit, I do respect the styles of others while maintaining apps.)

Clearly, you can get addicted to prefixes (I remember the gold-old T.. classes of the Borland OWL e.g.).
But, the real faults are mostly not in the naming convention, but in the sluggishly chosen words.
These often tell alot of what will await you upon respection.

As to SPs: These mostly don't belong to the db: They are part of application code. The actions of these have a different semantics than the actual table names. Other than that, I'd rather prefer to be a Java guy loading bulks of packages into the server cache, be rid of SPs, and enforce the db administrators to wait for hours until the cache gets loaded (or be crashed because of DB changes).

Cheers
Hans