We often find when working with new programmers that they say our "rules" are hard to grasp and maybe a bit nonsensical.
All the yMonda coding rules have come out of painful experience and all have reasons behind them.
So I have set out below our methodology. You may or may not find it helpful, either way it might give you food for thought.
These "rules" establish the principles for setting up the architecture of an application. Once the architecture is established and development work has begun it is a lot harder to change the architecture. So getting it right is important.
There are of course applications where these rules seem unnecessary and over zealous but like most programmers, we aim to develop once and reuse many times. So it makes sense to assume the code, if not the application, may be reused in a situation where the rules become more important.
Title or Prefix?
When choosing the name of the field to contain Mr, Mrs, Ms, Dr etc.. the obvious choice might be to call the field "Title". This is a VERY ambiguous title if you excuse the pun. Likewise "Prefix" is not very descriptive. We use the term "Honorific" as it says what it does.
First name, forename, christian name, personal name or given name?
This is a fairly easy one to answer.
First name does not work where you have a mix of cultures. The first name in many Eastern cultures is actually the family name.
Forename does not work for the same reason.
Christian name can only be applied to Christians and strictly only baptised Christians, so that won't work.
Personal name is pretty good but may be confused with "nick name".
Given name was how our forebears referred to what we in the west call first name. It is understood by people from most countries and is therefore our term of choice
Last name, surname or family name?
Family name is used in preference to last name for the reasons given above.
Surname is not universally understood.
We therefore use the term FamilyName.
Why not use family_name or familyname?
FamilyName is shorter. We use what is known as UpperCamelCase because it is shorter, it is easier to read than all lowercase asyoucanseefromthisexample. It is unambiguous in cases where strings of words can be interpreted in several ways e.g. expertsexchange.
UpperCamelCase also allows for easy addition and identification of the object datatype identifier e.g. strFamilyName.
DateOfBirth, DOB or BirthDate?
For easy and quick identification we use BirthDate. In the same way we use EventDate, StartDate, EndDate. The principle is object first, attribute last.
What, no plurals?
This rule partly relates to tables and partly to straightforward simplicity. Over the years we have worked with programmers from all around the world and a surprising number of genuine dyslexics. Plural nouns can cause real problems and we have seen terms like "persons", "companys".
If you are working with something that you think should have a plural identifier, it is probably an array a table or a list. So why not say so? PersonArray for example, it is simple then to take each element of that "grouped" object. For a programmer with less than the full grasp of the English language CompanyArray, LorryArray and SheepList are easy to remember and this usage is a lot less error prone.
This brings us the vexatious naming of database tables.
What is in a table?
A database "table" as seen in a tool like MS SQL Enterprise manager is actually just a tabular display of a list of database objects. The table name is actually the name of the object (in the database it is the label for a reference). This is easily demonstrated by extracting the "table" to XML. You will then see something like:
You can see that the "table" name is used for the "wrapper" element.
To use the output XML the programmer will have to add an outer element to produce valid XML.
Below is an example of a table as named using our "rules"
It may seem odd at first but just remember you are referring to each object not the container for all the objects. I have also "normalised" the Address and Job.
Address1, Address2, Address3 Arrgh!
A huge number of websites are constructed by programmers who seem to think they must separate the first x parts of an address into individual fields. Why? They can't do anything sensible with these separate fields, so why bother? Maybe they think that one day they will be find some way to organise the data so that each field has a relevance.
The different postal authorities around the world have been grappling with this problem for a long time so why not base your structure on one of their formats? When the day comes that you actually get structured data you can then map it to your fields.
In the meantime if the data is unstructured just stick it in the "Street" field.
For example, UK addresses are held by the Royal Mail in the following fields:
Sub Building Name
Dependent Thoroughfare Name
Dependent Thoroughfare Descriptor
Double Dependent Locality
The structure we use is as follows.
AbodeNo The number of the abode within the building. The label would say something like "Flat or apartment number".
BuildingNo The building number.
BuildingName The building name.
For the sake of brevity we normally combine these three values and store in the BuildingName field.
Street If the following 4 fields are unlikely to be understood (by users) or if any of the address data is not separated then all the (unseparable) text goes in here.
SubLocality The area the Street is in (this is the least useful field but may be useful for locally based data).
Locality The village or part of the PostTown.
PostTown The main town or city.
County County e.g. Dorset.
PostCode Post or Zip code e.g. BA12 1NA.
Province England. The label for this might be "Province, Canton or State"
CountryCode UK (or GB).