Naming Conventions

Introduction

Naming is an important part of code quality and goes a long way in making the code base clear and consistent, making the developers job easier and increasing productivity.

Because we spend far more time reading code that writing it, taking the time to use appropriate and explicit naming is well worth the effort.

General Principles

In order to maintain clear and consistent naming:

• Use intention revealing names (eg. elapsedTimeInDays is better than numberOfDays)
• Avoid abbreviations whenever possible (eg. backgroundColor should not be named bgColor)
• Avoid ambiguity and don't be afraid to use longer names in order to do so
• Omit words which are not bringing meaning to the name
• Keep names consistent and refer to existing files and documentation if unsure of the appropriate naming
• Use one word per concept (eg. do not use get, fetch and retrieve in the same code base), refer to the lexicon for CC6 keywords

Variables and constants

When declaring a constant of type service/dao/worker or any other type where it wouldn’t make sense to have multiple instances in the same file, the constant should be named after the class name, for example:

public let queryService: QueryService

When dealing with errors, the error variable should consistently be named “error”, never “e” or “err”.

For example:

switch result {

  case .success:

    onApproveReject()

  case .failure(let error):

    onApproveReject(error: error)

}

Boolean variables or constants should start with any of the following:

• is
• has
• can
• should

Methods

Methods names should:

• Be named after the attribute whenever returning an attribute of the caller
• Start with a verb in all other cases

Whenever possible, prefer method names and use sites which form grammatical English. For example: 

x.insert(y, at: z)

Method names should be consistent throughout the application: if a fragment has a method redrawUIFromViewModel() to populate the UI, all fragments should call the method to populate the UI from the view model redrawUIFromViewModel().

To clarify the parameters' roles, prefix weakly typed parameters with a noun describing its role.

For example:

func addObserver(_ observer: NSObject, forKeyPath path: String)
grid.addObserver(self, forKeyPath: graphics)

Do not:

• Use “do” or “does” as part of the name as these auxiliary verbs rarely add meaning
• Use “and” to link parameter keywords.
• Call a method “create”, “get” or “delete”, unless what the method create / get / delete is obvious. Specify what is created / retrieved/ deleted.

For example, the following is not easily understandable:

public protocol InventoryTransferInteractor {

	[…]

	func create() throws -> GetInventoryTransferLines

	[…]

	self.inventoryTransferLineWorker.get(try self.create())

	[…]

}

A clearer way of doing this would be as follow:

public protocol InventoryTransferInteractor {

	[…]

	func createGetInventoryTransferLinesRequest() throws -> GetInventoryTransferLines

	[…]

	let getInventoryTransferLinesRequest = try self.createGetInventoryTransferLinesRequest())

	self.inventoryTransferLineWorker.executeGetInventoryTransferLines (getInventoryTransferLinesRequest)

	[…]

}

Classes and Protocols

Class and protocols names should be nouns or nouns phrase names.

Avoid using words which don’t add meaning, like “Manager”, “Processor”, “Info” and “Data”.

Protocols describing what something is should be defined as nouns (eg. FileUploadService)

Protocols describing a capability should be named using the suffixes -able. -ible or -ing (eg. Capturable).

CC6 Specific Principles

Methods

Any method whose main responsibility is to execute a request should be named using the following format: execute<RequestType> (_ request:  RequestType).

For example: 

public func executeGetUserDefinedCodes(_ request: GetUserDefinedCodes)

Workers

Workers should be named as per their entity: <EntityName>Worker

For example: AddressBookWorker

Services

Services should be named as per their entity: <EntityName>Service

For example: AddressBookService

DAOs

DAOs should be named as per their entity: <EntityName>Dao

For example: AddressBookDao

Requests

Requests names are built as <Action><Objects> where:

• Action can be Get / Delete / Create / Download / Upload / …
• Objects should describe the objects the action apply to

For example: GetMediaAttachments

For consistency, refer to the lexicon to know which term to use for each action.

Routers

All routing methods should be named as follow: routeTo<Destination>().

For example:

func routeToHome()