This topic covers best practices and guidelines for programming style, practices, and layout of code used when developing with LabKey. It does not prescribe the overall development or test procedures, debugging, or the deployment process.
Philosophy
LabKey does not wish to be overly prescriptive in setting out coding standards. Instead, the primary intent is to make sure that all developers are creating work that is as easily understood by others as possible.
This document is primarily concerned with the aesthetics of code (including scripts, SQL queries, XML, etc), It is not an attempt to capture functional standards (such as specific method, class, or file names that will be acted on in special ways). As such, we will establish a small number of unified guidelines across resource types, and defer to external resources for suggestions on many of the specifics.
Cross-Language Guidelines
Identifiers
- Use CamelCasing for all identifiers. Context will dictate whether the first character should be upper or lower case. Do not use underscores or other separators.
- Abbreviations and acronyms in identifiers should be in all CAPS. For example, “ID” or “URL”. Avoid abbreviations except for very standard and obvious ones.
- Strike a reasonable compromise between being descriptive and being verbose. Modern editors make it easy to type longer identifiers with statement completion, meaning there is much less incentive to use ultra-concise names.
- Except when needed to disambiguate, do not use prefixes or suffixes that indicate the type of a field.
Formatting and Layout
- Avoid making readers or editors with a standard setup do any horizontal scrolling to read your code. Wrap lines at a reasonable character count. Monitors are much bigger than they used to be, so in many contexts more than 80 characters is often reasonable.
- Use spaces instead of tabs for indentation. Four spaces represent one indentation unit.
- Apply additional indentation to wrapped lines. This may sometimes be a single indentation unit (4 spaces), and in others might align method argument parameters, etc.
- Use whitespace to separate logically separate elements. Usually a single blank line is enough.
Documentation
- Clearly document the functionality and intent of each section of code in-place.
- Use language-specific documentation features when available. For example, Java supports JavaDoc comments, which are specially formatted comments that can be used to build auto-generated documentation using standard tools.
- If you think any bit of code is clever, it deserves documentation. Clever code is typically hard to understand.
- Write in-line comments, not just a method or class level summary.
- Every time you touch a bit of code, improve it's documentation.
- Focus on writing meaningful commments. Documenting 'setName' with "Sets the name" or anything else that could have been auto-generated is not worth the time. Make documentation meaningful.
General
- When editing existing code, be consistent with the conventions in that file. It’s much harder to follow code flow when the formatting changes from line to line.
- Eliminate warnings raised by code editors whenever possible. If a warning is not applicable, suppress it when possible.
- Avoid usage of deprecated methods.
- Declare variables where they are first used, not at the top of the method.
Language-Specific Guidelines
Follow the general and language-specific conventions listed here. Some languages refer to external resources for additional standards. The guidelines here should take precedence when there is disagreement.
XML
- Avoid using explicitly named namespaces when possible. That is, if a document uses a single XSD as its schema, avoiding the namespace prefix on each element creates clearer, more concise XML.
JavaScript
- Prefer standalone .js files for code, instead of inline <script> tags.
- LabKey-specific JavaScript API guidelines:
- External guidelines:
- JavaScript documentation guidelines:
HTML
- LabKey-specific CSS guidelines:
- External guidelines:
SQL
- Use singular nouns for table, view, and query names.
- Capitalize keywords.
- Explicitly name all constraints. If you do not, they are assigned an auto-generated default name, which makes them much harder to manipulate later.
- Primary keys: PK_TableName
- Foreign keys: FK_TableName_ColumnName
- Indices: IDX_TableName_ColumnNames
- Unique: UQ_TableName_ColumnNames
- When there is no “natural” key for a table, use the table’s name as part of the key column name. For example, use “CustomerID” as the Customer table’s PK instead of “RowID”.
- GUID columns should be named with a “GUID” suffix. For example, “CustomerGUID”.
- Junction table names should be the concatenation of the two linked table names. For example, “AppointmentProvider” is a junction table connecting “Appointment” and “Provider”.
- LabKey-specific guidelines for schema upgrade scripts:
- External guidelines:
Java
Related Topics
