The Standard Code Writing & Commenting Format¶
Create a New File¶
Whenever you create a new file, the first line of the file should start with a comment dedicated to the file. The comment structure should be like
/******************************************************************
// @desc : A short description of the file
// @author : The name of the developer creating the file
// @files_required : Name the required system files
// @requested_modules: Name the module dependencies, if any
// @created_date : Time and date when the file is created.
/******************************************************************
Functions¶
It is important that we write meaningful function names, following the lowerCamelCase naming convention.
Before you start writing the method, you should include a comment stating its purpose.
Remember, to indicate the data type for a @param
or @return
tag, put the data type in {} brackets
/******************************************************************
// @desc : A short description of the function
// @param : {data_type_1} paramName1, {data_type_2} paramName2
// @return : {data_type}
/******************************************************************
Example
function processOrder (pdt, x) { # Note spaces before, after function_name & parenthesis
const MAX_ITEMS = 10; # maximum number of packets
const MASK = 0x1F; # mask bit TCP
return true;
}
Avoid obvious comments such as:
----------------------------------------------------------------------------------------------------------------------------------------------------
if (a == 5) // a equals 5
counter = 0; // setting the counter to zero
Try to write comments that explain higher level mechanisms or clarify difficult segments of your code. Do not use comments to restate trivial things.
Variables¶
Variables names should use lowerCamelCase. They should also be descriptive. Single character variables and uncommon abbreviations should generally be avoided
var stringMatches = item.match(/ID_([^\n]+)=([^\n]+)/); # Execute a regex : Add a comment to a global variable
----------------------------------------------------------------------------------------------------------------------------------------------------
var numberCount = 0; # The local variables need not to be described each time. Don’t wastes your time writing needless comments.
Special Tags¶
When working on code as a team, adopt a consistent set of tags to communicate among programmers. For example, use a TODO: tag to indicate a section of code that requires additional work
function estimate (x, y) {
// TODO: implement the calculations
return 0;
}
Few special tags are
-----------------------------------------------------------
| BUG - a known bug that should be corrected. |
-----------------------------------------------------------
| FIXME – should be corrected. |
-----------------------------------------------------------
| HACK – a workaround. |
-----------------------------------------------------------
| TODO – something to be done. |
-----------------------------------------------------------
| UNDONE – a reversal or "roll back" of previous code. |
-----------------------------------------------------------
| UX – user experience, notice about non-trivial code.|
-----------------------------------------------------------
End of the File¶
Signal the end of any file with the comment structure as below
/******************************************************************
// EOF : File_Name (Signal the end of a file)
/******************************************************************
Committing the Code¶
Follow the below guidelines while pushing the code to the GIT repository:
- Always create a README.md file using the Markdown Language format.
- While pushing the code to the repo, add a valid description of the work you have done.
- Commit code in batches, please avoid small code commits.