Alpha Five Naming Recommendations
by Cal Locklin, Oct. 2, 2002 (rev. 04/04/2008)
The purpose of this document is to present some naming guidelines which will make it much easier, faster, and significantly more efficient to run text searches in scripts or, especially, with the A5 documenter or the AIMS App Analyzer when debugging or updating. This increased efficiency can be translated into cost savings, reduced frustration, and happier customers because fewer items will be missed when making changes.
Although a fixed naming convention for all A5 developers might be useful, the primary purpose of this document is to provide some guidelines and examples.
The underlying principle can be summarized in one word: unique. By making the name of each field, index, variable, layout, etc. unique, text searches will be more precise thus allowing the developer to fully utilize the power of these text searches to quickly and efficiently update or debug an application.
- A prime example of a commonly used form name that is not unique is "Rep" (as in 'sales rep'). A text search on "rep" would find every instance of "Report", "Type: Report", "Print Report", "representing", "preparing", etc. I know this one particularly well because I once ran a search on someone else's application that had 5 pages of hits (about 20/page) but only two were valid! A much better name would be "Sales_Rep".
- Another common mistake is to name a form "Menu" - imagine how many references there are to 'menu' in one application! Instead, use names like "Menu_main", "Menu_utils" (don't use "Menu_maintenance" because it contains "Menu_main" - see #2 below), "Menu_reports", etc.
The trick is to come up with a standardized method for creating unique names so a photographic memory isn't required in order to remember every name that has been used. The following guidelines are intended to do this...
Of course, there will always be times when a name, or portion of a name, gets duplicated by mistake but it will make text searches for debugging or updating much easier and faster if an honest attempt is made to follow these guidelines.
- Field names, index names, and variable names should be unique from each other whenever possible. A common mistake is to give indexes or variables the same name as the field name. The solution I prefer is to use suffixes "f" for field names, "v" for variables, and "_" (underscore) for index names -- Cust_Namef for the field, Cust_Namev for variables, and Cust_Name_ (end with an underscore) for the index. Another option is to simply use different names in each case. For example: Zip4 as the field name, Zip_4 for the index, and Zp4 for the variable. However, since simply using different names isn't a "standardized" method, it is more prone to mistakes.
By using the underscore as a suffix for index names, they are easier for users to read. If a prefix such as "ndx" was used instead (similar to Access conventions), the need for longer names would be greater (see #7 below) and many users might find the index names less intuitive.
The logic for always using the field name suffix ("f") should be obvious. However, the reason for using the underscore on all index names needs a little explanation. Of course, using the underscore for an index that is based on a specific field (i.e., Cust_Namef => Cust_Name_) makes it easy to distinguish the two. The other advantage of putting the underscore on all developer-created indexes, even if the index is not based on a specific field, is that it allows you to distinguish indexes that you have created from indexes that are system generated (A5 will build its own indexes if necessary for set relationships and certain field rules) - this can be significant when updating the application or rebuilding indexes. For this reason, try to always follow the suffix rule - or whatever rule you choose - for indexes whether or not they are related to fields.
Another advantage to this technique of using standard suffixes is that it can make expressions easier to read. For example, in this function - LookupN( "F", parentform:prod_id.text, "Pricef", "Child", "Prod_id_") - it is obvious without going to the help file that "Pricef" is a field name and "Prod_id_" is an index name.
Note: Many variable names have no relationship at all to the field names so leaving the "v" off of these 'unrelated' variable names will not effect text searches.
- Remember A5 capitalization issues when setting up field names, index name, table names, and layout names. Many people like to use the method often used by Access developers which uses prefixes and capitalization for each 'word' - such as fldMiddleName. In fact, I like this myself. However, Alpha will change it to Fldmiddlename which is not nearly as readable. This is why I use underscores between "words" so it would look like this: Fld_Middle_Name. (Actually, this name is too long to meet the recommendation in item 7 below. I would probably use something like: Mid_Namef. It isn't as pretty but it's basically bullet-proof.)
- Avoid using one name 'inside' another like Zipcode and Zipcode4. Better to use Zipcode and Zip4 or Zip_code4. Or, applying rule 1 above, Zipcodef is already unique from Zipcode4f. Another advantage in this case is that you could easily run a search for "zipcode" if you wanted to find all references to either Zipcodef or Zipcode4f. If you ran a search on just "zip" you might also find, for example, references to zip files used for backup routines.
- Use names consisting of at least two words for forms and other layouts to make duplication of text strings less likely. ie, never Menu but Menu_main. This is also a good idea for field names whenever possible.
- Never leave blank spaces in layout names. This eliminates the problem of searching a documenter and finding the text "401K Forms" somewhere else such as on a button when you really want to find only references to the form itself. Using an underscore instead of the blank space (401K_Form) will resolve most of these issues.
NOTE 1: Alpha will not allow you to leave blank spaces in field, index, or variable names.
NOTE 2: If you avoid using blank spaces in names, you can select the whole name by just double clicking it. This is slightly faster and definitely more accurate than highlighting the name 'manually'.
NOTE 3: The same applies to table and set names - see the last item for details.
- Never use the same name for two different types of layout. In other words, don't have both a form and a report called "Customer_List"; instead, call one of them something different like "Cust_List". If you need an additional form or report that is similar, either give it a completely different name or call it Cust2_List rather than Cust_List2 so that the phrase "Cust_List" is not repeated. (This is another reason to use double names; "Cust2_List" may look strange but "Cust2omer" looks even stranger.) Of course, you could also eliminate "Cust_List" and just have "Cust_List1" and "Cust_List2". (I've considered using layout suffixes such as "r" for reports, "m" for forms (since "f" is already used for fields), "b" for browses, "l" for labels, and "t" for letters. This would probably be "good form" but I haven't found it to be worth the effort - yet.)
- Try to keep field names and index names to 10 characters or less. Although this is not specifically required by Alpha Five, there are certain situations during development or application updates which could cause longer names to become truncated - and truncated names will almost always cause problems that will have to be fixed before the database can be used again. Index names can similarly become truncated so starting with a 10 character name is always safe. This truncation won't happen if all files are handled and copied correctly but we all make mistakes occasionally.
(Yes, I've broken this rule a few times myself - I've also regretted it on a few occassions!)
Another reason for keeping names short is that it makes complex expressions faster to type and expressions only allow a limited number of characters. Short names won't use up the character limit nearly as fast.
NOTE: Name length is generally not an issue with layout names (forms, reports, letters, etc.) up to their 24 character limit.
although it is best to limit these names to 23 characters (one less than the 24 allowed) because the 24th letter can get truncated when copying them between tables. Version 5 has eliminated the 23 character issue when copying.
- Although not directly related to the previous naming recommendations, the recommendation of experienced A5 developers is that the restriction on blank spaces should also be applied to table and set names. In certain XBasic routines, such as the Append routine, a blank space in a table name will mean that some lines of the code must contain the blank space while other lines must replace the space with an underscore. Getting the combination correct can be frustrating to say the least. The underscore is easy to use and avoids the potential risks and significant time required to fix set relationships and script references should the need arise. Also, as discussed in #4 regarding layout names, using the underscore makes searches more accurate and selection faster. (It's my personal opinion that they're also easier to read because you know that "OEM_quote_form" is in fact the name of the form when you see "Go to the OEM_quote_form." However, if you read "Go to the OEM quote form" without the underscores you might wonder what the name of the actual form is. Maybe the form is actually called SF03_quotes - which is actually true in one of my apps but the Help instructions simply refer to it as the OEM quote form.)
- This one could be considered personal preference but try to keep variable names to a reasonable length. Extremely long variable names take longer to type, can cause complex expressions to become too long (expression length was increased from 1024 awhile ago but is still limited), and in some cases they can make a line of code so long that it affects the overall readability. Clarity is one thing, excessive detail is another - instead of varC_Customer_Spouse_First_Name, why not just Spouse_fname? Even the "varC_" should be unnecessary since it should be obvious that it's a variable and we know that most names are character values.
I think most people would find this far more difficult to read: (and in A5 it will probably go off the right side of your screen)
varC_Customer_Spouse_Name_Full = varC_Customer_Spouse_Name_First + IF(varC_Customer_Spouse_Name_Middle_Initial<>"",varC_Customer_Spouse_Name_Middle_Initial+". ","") + varC_Customer_Spouse_Name_Last
SName = Spouse_FName + IF(Spouse_Mid<>"",Spouse_Mid+". ","") + Spouse_LName
And, there will always be those who say, "This doesn't apply to me because I never run text searches in my application." That's fine. Just be aware that there are other issues with naming conventions besides the 'search' issue that will cause you to spend extra time fixing/updating your own application and/or you will pay extra money to another developer if you get beyond your capabilities and need additional help. About 2-3 times a year someone wants me to fix or finish an application that they started and every time, so far, I have had to spend additional time working on it (i.e., I had to charge them more) because of bad naming conventions that made it hard to understand what was going on or to find where specific layouts, scripts, etc. were used. So go ahead, take the "easy" way out - one way or another you'll pay for it later. It's better to think long term because what's easy initially isn't necessarily the most efficient in the long run.
NAME LENGTH CLARIFICATION: (Added 2/16/12)
I've seen a lot of misunderstandings about this issue so I hope the following will help clarify it.
NEVER: (Added 4/4/09)
- Only the field name and index name have a potential length restriction beyond what is allowed by Alpha or Windows. (See item #7 above.)
- If you don't restrict the field and index names to 10 characters, it's a good idea to make sure the first 10 characters (not 8!) are unique just in case you do something to cause them to get truncated to 10 characters.
- To the best of my knowledge there is no reason to limit anything to 8 characters in A5. There are no "DOS vs. Windows" issues built into A5.
- There is no 'safety' benefit to arbitrarily restricting the length of any other names beyond what A5 (for layouts, scripts, functions, operations, variables, etc.) or Windows (for table/set names) allows.
- These are the only benefits I can think of to arbitrarily restricting other name lengths:
NOTE: This primarily applies to table, set, and folder names since A5 has reasonable limits on the length of layout and operation names. However, as noted above, very long variable names can also be an issue at times.
- to reduce your typing,
- to keep expressions short enough to work (they can now be longer than 1024 but I believe there is still a limit),
- to make the full name visible in certain lists (this one is most important to me)
Example, there are some developer dialogs in A5, such as when creating a field rule table lookup, that list field names and the dialog is not resizable. With long folder names and long table names it's very possible that you won't be able to see the actual field name in the selection list.
Comments from readers:
- Create both a script and a function with the same name.
The error routines can be used to return the line number that the problem occurred on and get the text from that line. However, if there is both a script and function by the same name, they can't tell if the problem occurred in the script or the function and, as a result, may show the wrong line of code.
- Create a script or function name that ends with a number.
When an error occurs, A5 can return the name of the script or function the error occurred in. (See the error_script_get() function.) In addition, that script/function name returned by error_script_get() sometimes has a 0 or 1 appended to the end of it. (I have no idea why these different names are returned.) If the name already ends with a number, that number might be incremented by one or, sometimes, two. This makes it very difficult for an error routine to determine the correct script/function name. A name with no number on the end could show up in an error routine as the plain name or with either a 0 or 1 added to the end. A name that should have the number "1" on the end could show up in the error routine as a 1, 2 or 3. It is very unlikely that you will either find or create an error routine complex enough to decrement and test for each possibility.
Worse yet, even if you did create an error routine complex enough to test for each possibility, any developer who creates a script/function name that ends with a "1" is likely to also have a script/function by the same name with either no number on the end or ending in 0 or 2 and it would now be impossible to tell which one the actual error occurred in.
I've begun getting some comments from readers so I decided to post some of them:
- As far as field name changes are concerned, I feel a real need to get these unique and in conformance (?) with your white paper on the subject. All I can say about AIMS and your white paper, is that I would have saved months of frustration had I had it earlier.
- Genius! Pure genius!
- If you haven't already read this - my 2 cents worth is to download and digest Cal Locklin's 'Alpha File naming Recommendations'. If I had read this before starting down the A5 trail, I would have saved may hours of regurgitating (?) my tables and file names.