Difference between revisions of "Coding standards"

Revision as of 07:35, 27 June 2019

Object properties

Getters

Avoid throwing exceptions. A getter should provide access to the field, and should not result in an exception. There are occasions when this rule can be relaxed (such as indeterminable exceptions like OutOfMemoryException, or deliberate exceptions such as IllegalStateException), but things like NullPointerExceptions should not occur.

Must be repeatable. Each call to a getter should result in the exact same response. As a general rule, you should not create new objects. If you do, you should make sure they are always guaranteed to be equal (this may be hard if you are not responsible for the other code).

Setters

Order cannot matter. The order in which setters are called should have no effect on the end result. Calling setA() then setB() should end with the same result as setB() followed by setA().

RESTful URL endpoints

URL structure

The API endpoints should incorporate the plural of the entity (i.e. "users" rather than "user").

/<category>/<entities>/<entityId>
/<category>/<entitiesA>/<entityIdA>/<entitiesB>/<entityIdB>/<entitiesC>/<entityIdC>

When the identifier is something other than an identifier, we alter the path variable accordingly:

 /<entitiesByName>/<name>
 /<entitiesBySize>/<size>
 /<entitiesById>/<entityId>

As the "ById" pattern is so common, we choose to shorten it by removing the 'ById', so that it becomes:

 /<entities>/<entityId>

Optional parameters (such as those used for ordering results, for example) should not appear in the URL path, but in the query parameters.

Here are some examples:

/user-management/users/{userId}
/user-management/usersById/{userId}
/user-management/usersByName/{name}
/user-management/users/{userId}/features
/user-management/users/{userId}/features/{featureId}
/user-management/groups/{groupId}/users?sort=name

Verbs

/users

/users/<userId>

/users/<userId>

/users/<userId>