Coding Standards for Fields

Contents 1 Naming Fields 1.1 Use a Full English Descriptor for Field Names 2 Naming Constants 3 Naming Collections 4 About Field Visibility 4.1 JavaScript Fields 5 Documenting a Field 6 Always Initialize Static Fields

Naming Fields

Use a Full English Descriptor for Field Names

You should use a full English descriptor to name your fields to make it obvious what the field represents. Fields that are collections, such as arrays, should be given names that are plural to indicate that they represent multiple values.

//Different field names in Java and JavaScript
firstName
zipCode
unitPrice
discountRate
orderItems
sqlDatabase

//Different field names in PHP
$firstName
$zipCode
$unitPrice
$discountRate
$orderItems
$sqlDatabase

Naming Constants

The recognized convention for constants is to use full English words, all in uppercase, with underscores between the words (NPS, 1996).

//Constants
MINIMUM_BALANCE
MAX_VALUE
DEFAULT_START_DATE

Naming Collections

A collection, such as an array, should be given a pluralized name representing the types of objects stored by the array. The name should be a full English descriptor with the first letter of all non-initial words capitalized.

//Naming Collections in Java and JavaScript
$customers
$orderItems
$aliases

//Naming Collections in PHP
$customers
$orderItems
$aliases

About Field Visibility

The Vision team (1996) suggests that fields not be declared public for reasons of encapsulation, but I would go further to state that all fields should be declared private. When fields are declared protected there is the possibility of member functions in subclasses to directly access them, effectively increasing the coupling within a class hierarchy. This makes your classes more difficult to maintain and to enhance, therefore it should be avoided. Fields should never be accessed directly, instead accessor member functions should be used.

• public. Do not make fields public.
• protected. Do not make fields protected.
• private. All fields should be private and be accessed by getter and setter member functions (accessors).

JavaScript Fields

Documenting a Field

Every field should be documented well enough so that other developers can understand it. To be effective, you need to document:

1. Its description. You need to describe a field so that people know how to use it.
2. Document all applicable invariants. Invariants of a field are the conditions that are always true about it. For example, an invariant about the field $dayOfMonth might be that its value is between 1 and 31. By documenting the restrictions on the value of a field you help to define important business rules, making it easier to understand how your code works (or at least should work).
3. Examples. For fields that have complex business rules associated with them you should provide several example values so as to make them easier to understand. An example is often like a picture: it is worth a thousand words.
4. Visibility decisions. If you've declared a field to be anything but private then you should document why you have done so.

Always Initialize Static Fields

Static fields, also known as class fields, must have assigned valid values because you can't assume that instances of a class will be created before a static field is accessed. This is a problem only if you choose not to use accessor member functions for static fields (With accessor member functions you can always use lazy initialization to guarantee that the value of a field is set. The use of accessor member functions to encapsulate fields gives you complete control over how they are used, while reducing coupling within your code.