1
edit
Changes
→Coding Standards OOP344 northWind87: added the rest of the coding standards section, hope it's not too long....
== Coding Standards ==
Coding standards are important if we want code to be readable. Now the jist of these rules is that they're "common sense" with readability in mind. The most important section is the commenting section as it is basically arbitrary while all the others should be more or less common sense. In any case, the entire thing is up here for reference purposes. We should all attempt to follow these guidelines when writing code.<br/><br/>
While no one will be prosecuted or killed if they forget one or more of these, the others will gently '''remind''' the person in question to '''follow the guidelines''' :)
=== Naming Conventions ===
* ''' Camel Notation ''' should be used for variable names and function names
** ''' ie ''' <code>myVar, bigInt, getNumber(), myFunction()</code>
* Class names should always be ''' First-Letter Capitalized '''
** ''' ie ''' <code>TestClass, DynamicStack, PeanutButter, Hammer</code>
* Compiler directives should always be written in ''' All Lowercase '''
** ''' ie ''' <code>#define, #ifndef</code>
* Compiler definitions should be ''' All Uppercase ''' and should only use underscore where a gap is required
** ''' ie ''' <code>IO_CTL_LARGEFILE, SOME_DEFINITION</code>
* Header file defines should be preceeded and followed with ''' Two Underscores '''
** ''' ie ''' <code>__CIOL_H__, __IO_FORM_H__</code>* Pointer declaration should ''' emphasize the type ''' with the <b>"*"</b> being pushed against the right side of the data type as opposed to the left side of the variable name.** ''' ie ''' <code>char* str, int* num, void* addr</code>* Binary operators should have a space between them and their constituents ('''Note:''' This does not apply to unary operators such as ++ or []).** ''' ie ''' <code>x = 7, z += y, int i = 10, judge = y > 5</code>* As well, please leave a space after every comma and every semicolon if something follows it.** ''' ie ''' <code>foo(int firstInt, int secondInt, int thirdInt), x = bugSquish(parm1, parm2), for (int i = 0; i < 10; i++)</code>
* Finally, <code>void</code> should always be explicitly declared.
** ''' ie ''' <code>void doStuff(void), int getInt(void)</code>
=== Statement Notation ===
for (
do (</pre>
In the same sense, the first left parenthesis should immediately follow the function name when a function is called.<br/>
''' ie ''' <code>x = getInt(), someInt = y + bigSum(y, r)</code>
=== Code Blocks ===
Both function blocks and loop blocks should open on the same line as the declaration statement preceeding preceding them; however, function blocks should open immediately after the last right parenthesis while loop blocks should open one space after the last right parenthesis.<br />
''' ie Functions: '''
<pre>
for (int i = 0; i < 15; i++) {
do (blah) {</pre>
=== Comment Blocks ===
All functions should have a comment block preceding them which should explain what the function does in a few brief sentences, what parameters it receives with each parameter having a section preceded by <code>@param</code>, and anything that the function may return preceded by <code>@return</code> at the end of the block. Try to keep things lined up so that they're easier to read.
Here is an example from Assignment 1 utilizing the io_strcpy() function:
<pre>
/*Copies a given number of characters from one string to another.
*Self copying is allowed. Does not stop at null-terminator, always copies
*the given number of characters.
*
*@param const char* src address from which to copy characters.
*@param char* dest address to which characters will be copied.
*@param int n number of characters to copy.
*
*@return the address of dest if copy was successful, NULL otherwise.
*/
char* io_strcpy(char* dest, const char* src, int n){
</pre>
Commenting within the function should be generally organized, that's about it for in-function commenting.<br/><br/>
That's about it folks, feel free to add or remove anything if you feel so compelled but please consult the rest of the group first if it is a major change.<br/>
'''-northWind87'''
== Announcements ==