This application note pertains to Mr Architecture 3.0. This note was last updated on 16th April 2005 to expand the Directories section and add the Packages section. This document refers to the naming conventions used within Mr Architecture and recommended for Mr Architecture applications. Directories Directories containing source files, object files, mapped servlets, JSPs, cascading stylesheets, images and user documentation should be named in lowercase, because this is the prevailing convention for the Worldwide Web. Consider placing source and object files under WEB-INF so they are not served to users. Applets may have to expose their object files, so in this case it makes sense to place these alongside other publically accessible resources. Directories containing other developer resources, including system and API documentation, should be named in title case. Access to these directories should be restricted to developers. The following names are suggested for directories within the Mr Architecture project and web applications based on it: command Mr Archtecture CommandServlets (usually virtual through servlet mappings in web.xml) images raster images jsp Java server pages logs log files (consider placing this under WEB-INF so it is not served) help user instructions (usually virtual through servlet mappings in web.xml) lib external project dependencies (consider using WEB-INF/lib for server-side dependencies) object object files and housekeeping scripts (consider using WEB-INF/classes so this is not served) servlet other servlets (usually virtual through servlet mappings in web.xml) source source files and build scripts (consider placing this under WEB-INF so it is not served) style cascading stylesheets and associated resources ui user interface servlets WEB-INF directories in a web application which are not served The following names are suggested for developer resources: API API documentation (usually a subdirectory of Docs) Docs project documentation Data database scripts, import files and dump files Internal internal API documentation (usually a subdirectory of Docs) Model modelling files Standards coding and other applicable standards Tool tools and documentation Web web standards and documentation Files in General Files should be named using title case for each word or abbreviation comprising their name, unless they are a shell script (see the next section) or in a directory containing only lowercase names- in those cases lowercase can be used. index.html files must always be in lowercase, and you should consider using this convention for other web pages and resources also. Build and Other Housekeeping Scripts The primary aim is that the build process is platform independent. To this extent, Mr Architecture supports POSIX compliant shells, the RISC OS obey command interpreter and the widely deployed Windows command batch interpreter. All shell scripts should end in ".sh". All shell scripts should be named with only lowercase letters: this makes typing them on case sensitive systems easier. e.g. makea.sh. All shell scripts should be simple enough that BatchFileGenerator tool is able to do a reasonable and functional job of translation. Anything more complicated should be in an ANT script (named using the same conventions of case as shell scripts) to ensure platform independence. Within such scripts, however, build targets should be named in with title case for each word or abbreviation comprising them, except the first word or abbreviation, which must be in all lowercase letters. All batch files should be generated from shell scripts using the BatchFileGenerator tool, and should end in ".bat". All batch files should be named with title case for each word or abbreviation comprising the name. e.g. MakeA.sh. If you are beginning with batch files, and need shell scripts, consider using the SourceFileRewriter tool, which will also convert the line endings of source files and CVS control files to those of your chosen platform. All obey files should be generated from shell scripts using the ObeyFileGenerator tool, and should end in ".oby". All obey files should be named with title case for each word or abbreviation comprising the name. e.g. MakeA.oby. The form of a script name is a verb, optionally followed by a noun, optionally followed by an adjective describing the new state of the noun: this is a verb phrase. Verbs recognised by BatchFileGenerator and ObeyFileGenerator, and the meanings intended for them are given in the following table: "Switch" is assumed. To change the state of something to on or off use "(On|Off.)" Count Generate statistics for files. Create Produce new files which have no counterpart on this system. Distribute Distribute multiple copies of files within one system. Compare Push. Docs Short for "MakeDocs." Build source files as documentation files. Flush Empty a cache on a server. Heimlich Attempt to undeadlock a deadlocked server. Kill Delete files on one system. Make Build or deploy source files as intermediate files or final object files. Monitor Watch a running server interactivey. Push Move or copy files from one system to another. Compare Distribute. Refresh Synchronize working copies with a repository. Compare Update. Release Distribute multiple copies of files across multiple systems. Compare Push. Restart Restart a running server. Rewrite Convert existing files to conform to conventions. (Usually a once off operation.) Run Attempt to execute an application or test, starting or restarting any necessary servers. Shift Move or copy files on one system. Compare Release. Status Short for "ReportStatus." Report on the state of a running server and return. Strip Remove statements from source files. Tar Short for "ShiftToTapeArchive." Archive files. Unstrip Restore source files. Update Synchronize working copies on one system. Compare Refresh. Nouns recognised are: Jar Java archive. Ear Enterprise archive. War Web archive. Abbreviations of nouns recognised: A Architecture C Compilation of architecture and application Dev Development environment Prod Production environment T Tests Test User testing environment Adjectives recognised are: On The state of being engaged or in use. Off The state of being disengaged or disused. Variants of a script may be indicated by a number. e.g. makea2.sh. Packages Packages should be named in all lowercase- no exceptions. Package names should be as terse as possible, and multiple words should be abbreviated. Hyphens are illegal and underscores should be avoided. The following are suggested package names: .beanui classes supporting bean-based user interfaces .business persistent business objects and session beans .client classes supporting client-server operation: client-side .i18n localization components .io input/output components .collection collection framework .server classes supporting client-server operation: server-side .util utility and supporting classes Classes Class and interface names use title case for all words (and abbreviations) comprising them, except that initialisms are preserved. All public classes and interfaces should have a file to themselves, and any classes which are tightly coupled to them should be inner classes. Classes which are internal to a package but not tightly coupled to any one public class should also be declared in their own file. A class which provides static utility methods for use with objects extending or implementing a class or interface defined within the Java API shall be named as the plural of that class or interface. e.g. Strings. Consider placing such classes in the au.gov.tas.dpiwe.mr.util package if they are generally applicable. A class which provides utility methods (static or otherwise) for use within a class already defined in Mr Architecture should be named "...Utilities." e.g. PresentationUtilities. A class which provides one kind of utility method, possibly overloaded to deal with many cases, should be named for a noun corresponding to the verb which names the action the methods collectively perform. e.g. BeanBundler. An interface may be named for an adjective which collectively describes the methods it contains. e.g. Validatable. A tool class which provides facilities directly to the user of the system should be named for a verb phrase or a noun followed the word "Tool." e.g. SourceFileRewriter, DeploymentTool. A tool which recurses through directories should be named "Multi..." e.g. MultiCopy. Consider placing such classes in the au.gov.tas.dpiwe.mr.tool package if they are generally applicable. A class which provides an alternate implementation or definition of something commonly used in Java should be prefixed by "Mr." e.g. MrNumber. By convention, all classes generated by the DeploymentTool are prefixed by "Mr" or "Thin." By convention, local object interfaces should be named "...Object." An adapter class which allows an object to implement an interface should be named "...Object" also. A version of a class or interface which includes another class or interface as part of its definition may combine the names of the classes or interfaces it is a hybrid of. e.g. IterableCollection. Classes used as exceptions should be named "...Exception." Similarly, "...Error" should be used for errors. All other classes should be named for a noun phrase. Anonymous inner classes should be avoided for the most part. Beans, Tables and Composite Primary Keys Abstract entity beans should be named for the singular name of the entity they represent. Their corresponding table must have the same name. Composite primary keys should be named for the entity they uniquely identify followed by the words "PrimaryKey." Similarly for other unique and foreign keys. Do not use underscores in Mr Bean or table names. Mr Architecture has a facility to do a simple mapping to remove underscores when table names are set in stone. Methods Method names use title case for all words (and abbreviations) except the first. Initialisms in all but the first place are preserved unless otherwise indicated by an externally defined interface. In the first instance, method names should be as descriptive as possible to avoid confusion. However, if a method performs a very complex or unusual task which is difficult to qualify succinctly, it is probably better to give it a short and unique name which will inspire people to read its API documentation. e.g. Collections.evolve(). Where the implementation and meaning of a method is (likely to be) different for different types, avoid overloading and include the name of the class (or class of classes) to which the method applies in the method name. e.g. BeanCache.cacheBeanObject() is distinct from BeanCache.cacheEntityBean(), and most of the BeanCache hierarchy continues this convention of being explicit about method applicability. Fields All non-constant fields use title case for all words (and abbreviations) except the first unless otherwise indicated by an externally defined interface. Initialisms in all but the first place are preserved. Public constants are in title case unless otherwise indicated by an externally defined interface. Underscores can be used to delimit a group name for a constant from an instance name. e.g. Level_Debug for Messenger's "Debug" message level is one of a group of "Level" constants. Private or otherwise visibility restricted constants can choose between the conventions above. Do not use underscores to name fields. Note: When Mr Architecture refers to persistent fields comprising Mr Beans internally, it uses the fully title cased form. This is relevant to users of the facilities provided by the PresentationUtilities class and MetaData interface. Variables All non-constant fields use title case for all words (and abbreviations) except the first unless otherwise indicated by an externally defined interface. Short non-descriptive names can be used if the purpose of the variable is obvious from the context. To this end: i and j a commonly understood as integer counters; in, out and through can be used for naming input, output and throughput in String, stream or buffer processing methods. Exception variables should be named "...Failure" and describe the situation in which that exception might arise, rather than naming the exception. This will hopefully inspire authors to write better error handling code. Avoid naming exception variables e, x or ex.