15 KiB
Code Commenting And Documentation Authoring Guidelines
Part I. Code Commenting
Part II. Documentation Authoring
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. |