-
Notifications
You must be signed in to change notification settings - Fork 118
3.1. Code readability
The following are guidelines to improve code readability.
- Use the camel case naming convention.
- Makes names meaningful and descriptive of the role of the class.
- Avoid overly long names.
- Acronyms should be have only the first character upper-cased. MyJdbcUtils vs MyJDBCUtils
- Collections should be plural nouns or end in "Collection". i.e Devices or DeviceCollection
- JavaDoc is highly encouraged in any location where it would improve code readability
- JavaDoc is REQUIRED on all public methods and classes
- The amount and formatting of JavaDoc is left up the the individual developer and contingent on the code that is being documented -- This may change in the future
- Interfaces should be prefixed with "I" in almost every scenario, for example
IDatasource. - Interface names should be descriptive of their responsibility.
- Single method interfaces can usually be suffixed with "able" such as ICloneable, IPassivatable, etc.
- Most class names should be nouns.
- If implementing a single interface, base the name on that of its interface.
- If a class is the only implementation of an interface available in the system, the class can begin with "Default" or end in "Impl".
- A class which supplies or resolves another entity should be an XxxResolver, XxxProvider or XxxFactory
- Objects which hold others allowing the retrieval later should be a "Repository" or "Registry"
- Most other cases should have a noun as it's root where possible, Vehicle, ContentGenerator
- If a class is involved with another either by servicing or modifying the another or is just intimately involved in some way, including the name of that other as part of the name is encouraged. Examples: RepositoryListener, CustomerDetails, FooRegistry,
Package names should use the company domain prefixes, org.hitachivantara or com.hitachivantara depending if it's a CE or EE project.
Api's should omit the api token from package names. On the other hand, implementations should include the impl token on the package name. A package name should look something like this:
package <org/com>.hitachivantara . <project-group> . [impl] . <package-suffix>;
As an example, an api class would live in the following package:
package org.hitachivantara . det . data.access.endpoints;
It's implementation(s) would be in:
package org.hitachivantara. det . impl . data.access.endpoints;
Important: The presence of the impl token has additional consequences, as some tools use it as a reserved word to introduce behaviour. The maven-bundle-plugin is one of those cases, packages with impl or internal will not be exported by the resulting bundle. This is the intended behaviour as bundles should only depend on API bundles.