Custom Fields
Field names
Field naming is an important topic, as it can have a significant impact on the usability and maintainability of functionality within an org. A good name provides an "at-a-glance" understanding of the field's purpose and usage.
A good field name should follow these guidelines:
- Concise, but descriptive
- The field name should be as short as possible while still conveying the purpose of the field. Avoid using long or complex names that are difficult to read or understand.
- Avoid abbreviations, unless widely understood
- Abbreviations can be confusing and may not be understood by all users. Use full words or phrases whenever possible.
- Use consistent naming conventions
- Use a consistent naming convention for all fields; this makes it easier for users to understand a field's purpose intuitively
- Try to be consistent with its API name
- The API name should be as close to the field name as possible to avoid confusion between developer and user interactions
| Example | Good or Bad | Reason |
|---|---|---|
| CV Submitted Date | Good | The field name is concise and descriptive |
| Cust Name | Bad | The name is ambiguous and uses an abbreviation that isn't widely recognised |
| Placed Date | Mixed | The field name is concise. There is some ambiguity in the name, which a field description would remove |
| Legacy Email Address | Mixed | The fields name is concise, but the use of "legacy" is ambiguous and may not be understood by all users. A field description would help clarify the purpose of the field. |
| Do Not Headhunt | Good | The field name is concise and descriptive, and uses a consistent naming convention. |
Never use the same API name for a custom field as a seven20 field, e.g. seven20__Field_Name__c and Field_Name__c. This causes functionality depending on fields (e.g. custom field set configurations) not being able to access the non-namespace field, leading to unexpected behaviour.
Seven20 uses snake case for all custom fields and objects, using camel case can be a good way to avoid any future name collisions.
Field descriptions
Field descriptions are used to provide additional context or information about a field, and should always be provided unless the name of the field (both label and API) would provide an outsider with enough context to understand the field's purpose. If there is any ambiguity or quirkiness to a field's name or purpose, a description should be provided.
Bad example:
- Field name: Submitted Date
- Field description: The date the application was submitted
- Field API name: Submitted_Date__c
The field name is ambiguous, as it could refer to either the date the application was submitted or the date the application was submitted to a specific stage. The field description does not provide any additional context or information about the field.
Good example:
- Field name: Submitted Date
- Field description: Date application first moved into the "Submitted" stage
- Field API name: Submitted_Date__c
The description provides additional detail that may not be initially obvious, and clarifies the purpose of the field, such as including key details about when the field value is set, and the context around when it is set.
Always assume the person reviewing the fields has no context about a project and so provide a field description. Your future self and others will thank you.