This topic covers recommended patterns for naming methods, fields, properties and classes in our JavaScript APIs. Capitalization guidelines have been chosen for consistency with our existing JavaScript APIs.
Avoid Web Resource Collisions
The web directory is shared across all modules so it is a best practice to place your module's resources under a unique directory name within the web directory. It is usually sufficient to use your module's name to scope your resources. For example,
mymodule/
├── module.properties
└── resources
├── web
│ └── **mymodule**
│ ├── utils.js
│ └── style.css
└── views
└── begin.html
Choose Concise Names
General Guidelines
- Avoid:
- Adding the name of the class before the name of a property, unless required for clarity.
- Adding repetitive words (such as "name" or "property") to the name of a property, unless required for clarity.
- Consider:
- Creating a class to hold related properties if you find yourself adding the same modifier to many properties (e.g., "lookup").
Examples
Some examples of names that should be more concise:
A good example of a concise name:
Choose Consistent Names
These follow Ext naming conventions.
Listener method names
- Document failure as the name of a method that listens for errors.
- Also support: failureCallback and errorCallback but not "errorListener"
- Document success as the name of a method that listens for success.
- Also support: successCallback
Failure listener arguments
- Use error as the first parameter (not "errorInfo" or "exceptionObj"). This should be a JavaScript Error object caught by the calling code.
- This object should have a message property (not "exception").
- Use response as the second parameter (not "request" or "responseObj"). This is the XMLHttpRequest object that generated the request. Make sure to say "XMLHttpRequest" in explaining this parameter, not "XMLHttpResponse," which does not exist.
Use Consistent Capitalization
General Guidelines
- Use UpperCamelCase for the names of classes.
- Use lowercase for the names of events.
- Use lowerCamelCase for the names of methods, fields and properties. See the special cases for acronyms below.
Special Case: Four-letter acronyms
- Treat as words and use lowerCamelCase
- Examples:
Special Case: Three-letter or shorter acronyms
- Use upper case for all letters when the acronym is used as the second word in a compound name.
- Lower case when the acronym stands alone or is the first word in a compound name.
- Examples:
Special Case: "ID"
- Always treat "ID" a word and lowerCamelCase accordingly, just like four-letter acronyms.
- Note that API capitalization is a different kettle of fish than UI capitalization – please remember to use "ID" in UI.
- Examples:
