IBIS-Q System Documentation - Naming Conventions
MixedCaseWithStartingLetterCapitalized
- db record name (primary key/ID)
- System generated indicator profile XML file names
- Query module XML file names
- URL control parameters like "PrinterFriendly", "GraphicType", "GraphicName", "Debug" etc.
- Java system property names
- Java Spring bean configuration names
- CSS/HTML style sheet classes
- Javascript prototype/class definitions
- Java class definitions and compiled class file names
- XSLT global parameter names. Typically because these values are passed to the system as it was received as an HTTP request parameter which as shown above is mixed case.
NOTES:
- Names are typically separated/delimited with a period ".". Java system properties, Spring bean configuration names, and indicator profile view names use this as a standard.
- Typically these are definitions of something - not instances of something. It is noted that this highly depends on the perspective e.g. db records from a db designer perspective would say that an indicator record is simply an instance of type indicator. From a user's perspective they're defining Low Birth Weight Utah v.s. US.
- Having user items named this way is easy to read and to communicate, and helps differentiate that this is a user named item.
mixedCaseWithStartingLetterLowerCase
- HTML element names/IDs
- Javascript variables
- Javascript functions
- Java variables
- Java methods
- XSLT template names
- XSLT template parameter names
- XSLT template and global variables
NOTE: Typically instances of something - although this depends on the
perspective. For Java, this is the standard and there's no way around it.
XSLT API TYPE TEMPLATES: These are named with a "api." type prefix. For example the "_html.xslt" XSLT file defines/contains a set of templates that make an API. These templates are meant to be able to be used, reused, and overridden. It is a good practice to have some type of prefix on the template name the developer has an idea of where to look to find the template. It also helps to provide some extra information about what that template does and where it fits in.
XSLT GLOBAL VARIABLES: These are named with a "filename." type prefix. This is similar to the API naming convention discussed above. If a global variable is to be used outside of the current XSLT, it is often prefixed with a value that matches the file from where it is defined. This again helps a developer to locate the variable and to provide a little insight.
XSLT API TYPE TEMPLATES: These are named with a "api." type prefix. For example the "_html.xslt" XSLT file defines/contains a set of templates that make an API. These templates are meant to be able to be used, reused, and overridden. It is a good practice to have some type of prefix on the template name the developer has an idea of where to look to find the template. It also helps to provide some extra information about what that template does and where it fits in.
XSLT GLOBAL VARIABLES: These are named with a "filename." type prefix. This is similar to the API naming convention discussed above. If a global variable is to be used outside of the current XSLT, it is often prefixed with a value that matches the file from where it is defined. This again helps a developer to locate the variable and to provide a little insight.
all_lower_case_with_words_seperated_by_underscore
- All filenames of the ibis system files except system generated files like indicator profiles and indicator views, and user defined files like module and module selection files.
NOTES:
- I just recently updated the map layers and java system configuration files to this standard.
- System related files are named this way as a carry over from old school Unix system administrators who pretty much insisted on all files being lower case. This also helps distinguish between system files and files that are auto generated or that users (super users) create and maintain.
ALL_UPPERCASE_WITH_WORDS_SEPERATED_BY_UNDERSCORE
- Javascript static constants
- Java static constants
- RDBMS table names
- RDBMS column names
- IBIS-PH related XML element names
NOTES:
- DB table and column names this is simply a standard that Garth carried over from years of db work - old habits die hard. Also, this is pretty much a standard that most db developers have used for 15+ years.
- IBIS XML element names are named this way because they are created from DB tables which are named this way. The module element names do NOT come from a DB table but the thought was/is to someday create a GUI front end for this that would keep the definition in a db. Plus it's consistent with all other IBIS XML elements. It also helps distinguish IBIS XML elements.