Permalink
Fetching contributors…
Cannot retrieve contributors at this time
349 lines (210 sloc) 15 KB

Code Commenting And Documentation Authoring Guidelines

Part I. Code Commenting

Grammar

Punctuation

Specific word usage

Trademarks

Part II. Documentation Authoring

Grammar

Styling

Specific word usage

Code Commenting Guidelines

Grammar

Active vs passive voice

Where possible, prefer active voice over passive.

Incorrect Correct
It can be put into the configuration mode by grounding the CONFIG pin on the transceiver. - You can put it into the configuration mode by grounding the CONFIG pin on the transceiver.
- To put it into the configuration mode, ground the CONFIG pin on the transceiver.
- Put it into the configuration mode by grounding the CONFIG pin on the transceiver.

Capitalization

  • Capitalize the first word in the description of an entity.
Incorrect Correct
checks to see if there is data available for reading Checks to see if there is data available for reading
@param len length of the buffer @param len Length of the buffer
  • Be consistent with the capitalization of boolean values.
Incorrect Correct
Returns True on success, false otherwise - Returns true on success, false otherwise
- Returns True on success, False otherwise

No possessive case

Do not use possessive case to avoid unnecessary personalization.

Incorrect Correct
method's output - method output
- output of the method

Present tense

Use the present simple tense instead of future, past, or present perfect.

Incorrect Correct
When specified, this value will be used in computing the voltage. When specified, this value is used in computing the voltage.
Once the data has been read… Once the data is read…

Second person vs the user / reader / programmer / engineer

Use second person when addressing the target reader of your comment.

Incorrect Correct
The user can easily override this method. You can easily override this method.

Third person vs infinitive

Use third-person verb forms in short descriptions of classes, methods, functions, etc., not infinitive.

Incorrect Correct
Get the proximity value from the sensor Gets the proximity value from the sensor

Punctuation

Comma in enumerations

Add an extra comma before the last item in a list joined by and / or.

Incorrect Correct
Returns raw values for the X, Y and Z axes. Returns raw values for the X, Y, and Z axes.

No period at the end of description

Do not put a period if the description of an entity is one sentence long.

Incorrect Correct
Returns the name of the sensor. Returns the name of the sensor
Sets the frequency modulation
Valid values are between 10 and 160 (in kHz)
Sets the frequency modulation. Valid values are between 10 and 160 (in kHz).
@param millis Maximum time in milliseconds to wait for the input
-1 means waiting forever (default)
@param millis Maximum time in milliseconds to wait for the input. -1 means waiting forever (default).

Exception: if the description contains more than one sentence, put periods after each sentence.

Specific word usage

Abbreviations and acronyms

  • Spell out the first occurrence or the first prominent use of an abbreviation or acronym, followed by a shortened form.
Incorrect Correct
@brief API for the GP2Y0A family of IR Proximity Sensors @brief API for the GP2Y0A family of infrared (IR) Proximity Sensors
  • Do not use Latin abbreviations.
Incorrect Correct
Works best with halved values; e.g., 1.0, 0.5, 0.25, etc. Works best with halved values; for example, 1.0, 0.5, 0.25, and so on.
  • Know exactly what the abbreviation or acronym means to avoid unnecessary duplication.
Incorrect Correct
- LCD display
- ISR routine
- LCD / liquid-crystal display
- ISR / interrupt service routine

Adjectives containing numbers

Adjectives of the form number + noun / participle should be hyphenated. It does not matter if a number is represented by one or more digits or spelled out.

Incorrect Correct
- 4 wire stepper motor
- 3 axis gyroscope
- zero based indexing
- one byte register
- 4-wire stepper motor
- 3-axis gyroscope
- zero-based indexing
- one-byte register

App vs application

Use app when referring to a program running on a device, and application when referring to a program running on a desktop / laptop computer.

Incorrect Correct
The wiki page for this device includes a link to an Android* application that can be used to read the device via NFC. The wiki page for this device includes a link to an Android* app that can be used to read the device via NFC.

Function vs method

If a function is associated with a class, use method instead.

Incorrect Correct
class WheelEncoder {
...
/**
* Starts the counter. This function also clears
* the current count and resets the clock.
*/
void startCounter();
class WheelEncoder {
...
/**
* Starts the counter. This method also clears
* the current count and resets the clock.
*/
void startCounter();

Onboard vs on-board

Use onboard.

Incorrect Correct
This ADC features an on-board reference and oscillator. This ADC features an onboard reference and oscillator.

Sensor name vs sensor model

Use a sensor name alone or a sensor model followed by a sensor name, not a sensor model alone.

Incorrect Correct
ADXL345 is compatible with… - The ADXL345 3-axis digital accelerometer is compatible with…
- The accelerometer is compatible with…

Exception: you can use a sensor model alone when introducing a sensor for the first time:

ADXL345 is a 3-axis digital accelerometer…

Setup vs set up

Setup is a noun, set up is a verb.

Incorrect Correct
It does not require any additional set up. It does not require any additional setup.
For instructions on how to setup…, refer to... For instructions on how to set up…, refer to...

Wi-Fi vs WiFi / Wifi / Wi-fi / wifi / wi-fi

Use Wi-Fi.

Incorrect Correct
It was tested with the XBee* S6B WiFi module. It is tested with the XBee* S6B Wi-Fi* module.

Trademarks

Intel products

Use the correct official names of Intel products. When in doubt, check the TM names database.

Incorrect Correct
It is a 64x48 pixel OLED display that connects directly to an edison via its 80-pin connector. It is a 64x48 pixel OLED display that connects directly to an Intel(R) Edison board via its 80-pin connector.

Note: if an Intel product has a legally approved short name, you may use it in subsequent instances, after spelling it out the first time.

Third-party technology

Add an asterisk (*) after a name to indicate a third-party trademark or registered intellectual property. If you are not sure whether an asterisk is necessary after a particular name, the rule of thumb is to put one, to be on the safe side.

Incorrect Correct
The Grove MQ2 Gas Sensor module is useful for gas leakage detection. The Grove* MQ2 Gas Sensor module is useful for gas leakage detection.

Trademark + noun

Always follow trademarks by an appropriate noun. For a list of approved nouns for a particular trademark, check the TM names database.

Incorrect Correct
It is a 64x48 pixel OLED display that connects directly to an Intel(R) Edison via its 80-pin connector. It is a 64x48 pixel OLED display that connects directly to an Intel(R) Edison board via its 80-pin connector.

Documentation Authoring Guidelines

Grammar

Capitalization

For titles, use sentence capitalization.

Incorrect Correct
Add a New Device Add a new device

Styling

Bolding

For GUI elements and file names, use bolding instead of quotes.

Incorrect Correct
In the “Environment Variables” window, click “OK”. In the Environment Variables window, click OK.
Copy the “example.zip” archive into the installation directory. Copy the example.zip archive into the installation directory.

Backticks

Enclose program commands, code blocks, and file paths in backticks (`).

Incorrect Correct
To create a new device, use the create-thing command. To create a new device, use the `create-thing` (rendered as create-thing) command.
Go to C:\Users\me\Documents\GitHub\intel-iot-examples-mqtt\support\aws. Go to `C:\Users\me\Documents\GitHub\intel-iot-examples-mqtt\support\aws` (rendered as C:\Users\me\Documents\GitHub\intel-iot-examples-mqtt\support\aws).

Links

Do not use embedded links to third-party websites.

Incorrect Correct
Create an account on Microsoft Azure, if you do not yet have one. Create an account on https://azure.microsoft.com/en-us, if you do not yet have one.

Numbered list vs bullet points

  • For a logical sequence of steps, use a numbered list.
Incorrect Correct
When running your C++ code on the Edison, you need to set the MQTT parameters in Eclipse. Go to "Run configurations", and change the "Commands to execute before application" to the following:

Click on the "Apply" button to save these settings.
Click on the "Run" button to run the code on the Edison.
When running your C++ code on the Intel® Edison board, you need to set the MQTT* client parameters in Eclipse*. To do that:
1. Go to Run configurations and, in the Commands to execute before application field, type the following:

2. Click the Apply button to save these settings.
3. Click the Run button to run the code on your board.
  • For a list of equally important options, use a bulleted list.
Incorrect Correct
From this exercise, developers will learn how to:
1. Connect the Intel® Edison board...
2. Run these code samples in the Intel® System Studio IoT Edition...
3. Set up a web application server...
From this exercise, developers will learn how to:
- Connect the Intel® Edison board…
- Run these code samples in the Intel® System Studio IoT Edition…
- Set up a web application server…

Specific word usage

Login vs log in

Login is a noun, log in is a verb.

Incorrect Correct
Provide your log in and password. Provide your login and password.
Login to your account. Log in( )to your account.

Click

Omit on after click.

Incorrect Correct
Click on Advanced system settings. Click Advanced system settings.

SSH

Do not use SSH as a verb. It is considered slang and is to be avoided.

Incorrect Correct
SSH into your Intel® Edison board. Establish an SSH connection to your Intel® Edison board.