Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-19T00:36:49Z

Enigma: /* Conclusion */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readability of the code an issue. Thus the definition of a good code involves a good self documenting structure and involves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derived form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call involves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Similar to the principles for naming methods, name your variables explicitly as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping structures .

for i = 1 to 7

The code suggests that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and parameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

*Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

*Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

* Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

* Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

* Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

* Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

* Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

* Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

* Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

* Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

* Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

* Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

* Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
* Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

* Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

* The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

* Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

===Conclusion===
Readability is one of the most important characteristics of good code. The use code with good self documentation and comments goes a long way in improving the readability of code.

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/ The Art of Commenting]

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips for Commenting]

[http://particletree.com/features/successful-strategies-for-commenting-code/ Types of Comments]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-19T00:35:30Z

Enigma: /* Tips for commenting */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readability of the code an issue. Thus the definition of a good code involves a good self documenting structure and involves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derived form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call involves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Similar to the principles for naming methods, name your variables explicitly as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping structures .

for i = 1 to 7

The code suggests that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and parameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

*Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

*Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

* Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

* Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

* Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

* Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

* Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

* Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

* Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

* Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

* Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

* Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

* Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
* Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

* Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

* The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

* Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

===Conclusion===
Readability is one of the most important characteristics of good code. The use of self documenting code and comments, goes a long way in improving the readability of code.

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/ The Art of Commenting]

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips for Commenting]

[http://particletree.com/features/successful-strategies-for-commenting-code/ Types of Comments]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-19T00:28:20Z

Enigma: /* Commenting */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readability of the code an issue. Thus the definition of a good code involves a good self documenting structure and involves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derived form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call involves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Similar to the principles for naming methods, name your variables explicitly as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping structures .

for i = 1 to 7

The code suggests that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and parameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

*Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

*Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

* Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

* Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

* Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

* Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

* Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

* Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

* Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

* Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

* Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

* Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

* Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
* Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

* Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

* The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

* Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/ The Art of Commenting]

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips for Commenting]

[http://particletree.com/features/successful-strategies-for-commenting-code/ Types of Comments]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-19T00:28:09Z

Enigma: /* Variables */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readability of the code an issue. Thus the definition of a good code involves a good self documenting structure and involves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derived form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call involves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Similar to the principles for naming methods, name your variables explicitly as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping structures .

for i = 1 to 7

The code suggests that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and parameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

*Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

*Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

* Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

* Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

* Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

* Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

* Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

* Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

* Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

* Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

* Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

* Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

* Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
* Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

* Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

* The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

* Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/ The Art of Commenting]

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips for Commenting]

[http://particletree.com/features/successful-strategies-for-commenting-code/ Types of Comments]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-19T00:27:36Z

Enigma: /* Methods */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readability of the code an issue. Thus the definition of a good code involves a good self documenting structure and involves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derived form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call involves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggests that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

*Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

*Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

* Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

* Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

* Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

* Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

* Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

* Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

* Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

* Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

* Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

* Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

* Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
* Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

* Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

* The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

* Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/ The Art of Commenting]

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips for Commenting]

[http://particletree.com/features/successful-strategies-for-commenting-code/ Types of Comments]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-19T00:27:21Z

Enigma: /* Coding Styles */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readability of the code an issue. Thus the definition of a good code involves a good self documenting structure and involves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derived form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggests that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

*Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

*Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

* Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

* Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

* Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

* Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

* Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

* Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

* Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

* Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

* Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

* Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

* Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
* Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

* Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

* The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

* Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/ The Art of Commenting]

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips for Commenting]

[http://particletree.com/features/successful-strategies-for-commenting-code/ Types of Comments]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-19T00:27:06Z

Enigma: /* Self-Documentation */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readability of the code an issue. Thus the definition of a good code involves a good self documenting structure and involves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derived form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggestst that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

*Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

*Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

* Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

* Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

* Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

* Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

* Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

* Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

* Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

* Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

* Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

* Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

* Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
* Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

* Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

* The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

* Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/ The Art of Commenting]

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips for Commenting]

[http://particletree.com/features/successful-strategies-for-commenting-code/ Types of Comments]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-19T00:26:54Z

Enigma: /* Introduction */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readability of the code an issue. Thus the definition of a good code involves a good self documenting structure and involves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derieved form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggestst that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

*Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

*Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

* Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

* Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

* Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

* Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

* Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

* Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

* Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

* Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

* Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

* Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

* Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
* Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

* Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

* The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

* Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/ The Art of Commenting]

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips for Commenting]

[http://particletree.com/features/successful-strategies-for-commenting-code/ Types of Comments]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:50:17Z

Enigma: /* References */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readablility of the code an issue. Thus the defenition of a good code involves a good self documenting sturcture and invloves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derieved form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggestst that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

* Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

* Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

* Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

* Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

* Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

* Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

* Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

* Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

* Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

* Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

* Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
* Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

* Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

* The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

* Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==Conclusion==

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/ The Art of Commenting]

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips for Commenting]

[http://particletree.com/features/successful-strategies-for-commenting-code/ Types of Comments]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:49:47Z

Enigma: /* References */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readablility of the code an issue. Thus the defenition of a good code involves a good self documenting sturcture and invloves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derieved form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggestst that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

* Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

* Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

* Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

* Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

* Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

* Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

* Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

* Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

* Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

* Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

* Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
* Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

* Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

* The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

* Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==Conclusion==

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/ The Art of Commenting]

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips for Commenting]

[http://particletree.com/features/successful-strategies-for-commenting-code/ Types of code commenting]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:48:41Z

Enigma: /* Four major types of comments */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readablility of the code an issue. Thus the defenition of a good code involves a good self documenting sturcture and invloves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derieved form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggestst that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

* Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

* Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

* Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

* Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

* Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

* Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

* Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

* Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

* Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

* Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

* Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
* Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

* Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

* The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

* Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==Conclusion==

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/ The Art of Commenting]

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips for Commenting]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:47:50Z

Enigma: /* Tips for commenting */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readablility of the code an issue. Thus the defenition of a good code involves a good self documenting sturcture and invloves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derieved form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggestst that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

1. Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

2. Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

3. Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

4. Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

* Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

* Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

* Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

* Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

* Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

* Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

* Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
* Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

* Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

* The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

* Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==Conclusion==

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/ The Art of Commenting]

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips for Commenting]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:47:12Z

Enigma: /* Tips for commenting */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readablility of the code an issue. Thus the defenition of a good code involves a good self documenting sturcture and invloves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derieved form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggestst that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

1. Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

2. Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

3. Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

4. Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

** Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

* Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

3. Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

4. Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

5. Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

6. Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

7.Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
8. Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

9. Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

10. The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

11.Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==Conclusion==

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/ The Art of Commenting]

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips for Commenting]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:47:00Z

Enigma: /* Tips for commenting */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readablility of the code an issue. Thus the defenition of a good code involves a good self documenting sturcture and invloves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derieved form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggestst that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

1. Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

2. Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

3. Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

4. Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

-> Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

* Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

3. Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

4. Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

5. Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

6. Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

7.Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
8. Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

9. Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

10. The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

11.Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==Conclusion==

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/ The Art of Commenting]

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips for Commenting]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:46:37Z

Enigma: /* Tips for commenting */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readablility of the code an issue. Thus the defenition of a good code involves a good self documenting sturcture and invloves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derieved form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggestst that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

1. Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

2. Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

3. Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

4. Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

* Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

* Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

3. Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

4. Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

5. Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

6. Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

7.Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
8. Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

9. Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

10. The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

11.Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==Conclusion==

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/ The Art of Commenting]

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips for Commenting]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:46:15Z

Enigma: /* References */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readablility of the code an issue. Thus the defenition of a good code involves a good self documenting sturcture and invloves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derieved form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggestst that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

1. Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

2. Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

3. Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

4. Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

1. Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

2. Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

3. Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

4. Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

5. Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

6. Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

7.Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
8. Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

9. Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

10. The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

11.Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==Conclusion==

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/ The Art of Commenting]

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips for Commenting]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:45:34Z

Enigma: /* References */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readablility of the code an issue. Thus the defenition of a good code involves a good self documenting sturcture and invloves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derieved form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggestst that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

1. Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

2. Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

3. Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

4. Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

1. Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

2. Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

3. Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

4. Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

5. Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

6. Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

7.Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
8. Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

9. Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

10. The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

11.Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==Conclusion==

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

[http://devjargon.com/developement/the-art-of-commenting-code/]

[http://www.devtopics.com/13-tips-to-comment-your-code/]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:44:13Z

Enigma: /* Tips for commenting */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readablility of the code an issue. Thus the defenition of a good code involves a good self documenting sturcture and invloves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derieved form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggestst that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

1. Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

2. Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

3. Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

4. Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

1. Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

2. Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

3. Align comments in consecutive lines:
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

4. Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

5. Be polite:
Always stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

6. Use a consistent style:
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

7.Do commenting as you code:
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
8. Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

9. Always update the comment when the code is updated:
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

10. The golden rule of comments: readable code:
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

11.Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==Conclusion==

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:43:13Z

Enigma: /* Tips for commenting */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readablility of the code an issue. Thus the defenition of a good code involves a good self documenting sturcture and invloves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derieved form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggestst that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

1. Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

2. Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

3. Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

4. Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

1. Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

2. Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

3. Align comments in consecutive lines
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

4. Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

5. Be polite
All stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

6. Use a consistent style
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

7.Do commenting as you code
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
8. Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

9. Always update the comment when the code is updated.
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

10. The golden rule of comments: readable code
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

11.Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==Conclusion==

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:42:51Z

Enigma: /* Tips for commenting */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readablility of the code an issue. Thus the defenition of a good code involves a good self documenting sturcture and invloves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derieved form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggestst that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

1. Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

2. Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

3. Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

4. Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

1. Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

2. Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

3. Align comments in consecutive lines
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

4. Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

5. Be polite
All stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

6. Use a consistent style
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

7.Do commenting as you code
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
8. Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

9. Always update the comment when the code is updated.
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

10. The golden rule of comments: readable code
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

11.Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==Conclusion==

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:42:29Z

Enigma: /* Tips for commenting */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readablility of the code an issue. Thus the defenition of a good code involves a good self documenting sturcture and invloves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derieved form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggestst that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

1. Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

2. Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

3. Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

4. Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

1. Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.

2. Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

3. Align comments in consecutive lines
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.

4. Avoid obvious comments:
Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

5. Be polite
All stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

6. Use a consistent style
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.

7.Do commenting as you code
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
8. Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”

9. Always update the comment when the code is updated.
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.

10. The golden rule of comments: readable code
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );

11.Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==Conclusion==

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:41:07Z

Enigma: /* Tips for commenting */

=Principle of Self-Documentation=
=Introduction=
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readablility of the code an issue. Thus the defenition of a good code involves a good self documenting sturcture and invloves many comments to aid the user or developer in understanding the code .

=Self-Documentation=
Self documentation of the code invloves using two methods
*1. '''Coding style'''
One of the major goals when embarking on a development project is to structure the application such that the code documents itself.
Thus if all the comments disappeared , the code should still be understandable to the developer

*2. '''Commenting'''
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derieved form the code itself .Explanation of an algorithm can only be done with the use of comments.

==Coding Styles==
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .

*If it looks like a cow and acts like a cow, call it a cow.
*Once you call it a cow, make sure you always call it a cow.

In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .

naming message as msg and sticking to it is a good coding style

naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult

===Methods===

When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.

user.GetID();
user.Get();
product.GetAvg();

Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.

user.getcustomerID();
user.Getnextcustomer();
product.GetAveragePrice();

The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.

Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.

===Variables===

Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".

Another example is the use of i,j in looping sturctres .

for i = 1 to 7

The code suggestst that there is looping structure here ,but nothing more

for dayInWeek = 1 to NUM_DAYS_IN_WEEK

Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .

==Commenting==
In software development, in-code documentation is a very important aspect of the code. Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Almost all the source code will need to be referred back in back in the future or it might also need to be reused. In any case the document that is provided is like a specification or a literal form of the code for any reader using it in the future. Without a good documentation, the reader will end up wasting a lot of time understanding the code or make dangerous assumption and misinterpret the code.

Even while documenting a code we need to take care that we neither comment the code way too much nor should be too less that its meaningless to the reader. Lets first take a look take a look at the different approaches to commenting; too much and too little:

Too Little

#include
#include
//This is a function
int calculateDistance(int x, int y){
. . . .}
//Main function
int main(){
int x=0;
int y=2;
calculateDistance(x, y);
printf("SUCCESS");
return EXIT_SUCCESS;
}

The above comment has way too little information for the reader to make any meaning out of it.

Too Much

/*These are two pre-defined header files that
I've included I'm going to be using printf()
from stdio.h and then I'll be usingEXIT_SUCCESS
from stdlib.h*/
#include
#incude

/*This function takes in the two variables
(x and y) and calculates the Distance
between the two. In the end it will return an
integer. I thought I'd include a few error
checks in the code but then decided
against it. They'll be added in version 1.1 */
int calculateDistance(int x, int y){
. . . .
}

//The function where the program starts.
int main(){
//These are the two variables use.
int x=0;
int y=2;

//Call the the calculateDistance function
calculateDistance(x, y);
//Prints that the function was a success
printf("SUCCESS");
//Exits the program
return EXIT_SUCCESS;
//End of the main function
}

And this code has way too much information. This is unnecessary and makes the program look huge and cluttered up.

===Four major types of comments===

1. Code Commenting - This refers to writing descriptive variable names that are self explanatory.

function addUserToDatabase(userName, userAge)

2. Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength

// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) ï¿½ cUser.nSize;
return cUser.nCurrentHitPoints ï¿½ nDamage;
}

3. Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function.

/*
* Summary: Calculate hitpoints after attack using formula
* new = current ï¿½ ((enemyStrength*3) ï¿½ size)
* Parameters: cUser ï¿½ object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
ï¿½
} // end calculateHitPoints

4. Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information.

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

===Tips for commenting===

1. Comment each level:
This is the first important rule that you need to remember. Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and results
Adopting comment standards is important when working with a team. Of course, it is acceptable and even advisable to use comment conventions and tools (such as XML in C# or Javadoc for Java) to facilitate this task.
2. Paragraph Comments:
On top of each block of code that is there in the program, add a comment explaining what exactly the following block of code will do.
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .
3. Align comments in consecutive lines
If there are codes in consecutive lines of the program, align them such that they start at the same point. This makes the program more readable.
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
You can use tabs to align them together. Also make sure you leave a small gap between where the code ends and the commenting begins.
4. Avoid obvious comments:

Avoid obvious comments in the code. This will only clutter up the code and distracts the reader with details that can be easily deduced from the code.

if (a == 5) // if a equals 5
counter = 0; // set the counter to zero

5. Be polite

All stay away from making any rude comments to the reader like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted.

6. Use a consistent style
Always use a consistent style of coding. Its always easier for reader to understand the code and documentation if the comments are in consistent style throughout the code.
7.Do commenting as you code
Its always good to make it a habit to comment the code as you write it. Its much easier to do the commenting it when the code is still fresh in your memory.
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
8. Comments should always be written as if they for you as much as it is for others:
When it comes to commenting code, think not only about the developers who will maintain your code in the future or reuse it later, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”
9. Always update the comment when the code is updated.
The comment needs to be updated whenever the code is updated. If this is not followed, the comments might end up confusing them and prove to be a curse to the developers rather than helping them. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant.
10. The golden rule of comments: readable code
Your code should speak for itself. Self explanatory code will make the life of the future reader of your code a lot easier.
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );
11.Get a friend to look it over:
Finally have someone else who has never seen the code go over it. The point of this is if they have any questions about any parts of your code you should comment that part better.

==Conclusion==

==References==

[http://www.devtopics.com/13-tips-to-comment-your-code/ Tips to commenting your code]

[http://www.cprogramming.com/tutorial/comments.html Commenting styles]

[http://codebetter.com/blogs/eric.wise/archive/2005/12/06/135418.aspx Code Self Documentation]

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:40:17Z

Enigma: /* Four major types of comments */

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:39:17Z

Enigma: /* Commenting */

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:38:40Z

Enigma: /* Commenting */

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:38:11Z

Enigma: /* Commenting */

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:37:12Z

Enigma: /* Commenting */

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:35:15Z

Enigma:

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:33:50Z

Enigma: /* Commenting */

CSC/ECE 517 Fall 2009/wiki3 14 rd

2009-11-18T19:33:30Z

Enigma: /* Commenting */

CSC/ECE 517 Fall 2009/wiki2 3 bd

2009-10-11T00:03:20Z

Enigma: /* Conclusion */

==Synchronizer token pattern==

==Introduction==

Web application developers and designers face the problem with maintaining normal flow of control when multiple form submissions are made in a website .
This situation typically occurs when a user clicks more than once on a submit button before the response is sent back or when a client accesses a view by returning to a previously bookmarked page. Control flow sequence is particularly important to preserve when form submission involves transaction processing on the server. There are many solutions to the situation ,some websites just warn the user not to submit twice once a submission is made and to wait for the response .In other cases we have client side and server side solutions to the problem .Server side solution being more reliable than client side .In the client side model the button is disabled based on a flag which is set once first submission is performed .Below we discuss some the ways this is handled in different in
different languages -

==Java==

Java uses the server side solution to solve this problem .The basic idea is to set a token in a session variable before returning a transactional page to the client. This page carries the token inside a hidden field. Upon submission, request processing first tests for the presence of a valid token in the request parameter by comparing it with the one registered in the session. If the token is valid, processing can continue normally, otherwise an alternate course of action is taken. After testing, the token resets to null to prevent subsequent submissions until a new token is saved in the session, which must be done at the appropriate time based on the desired application flow of control. In other words, the one-time privilege to submit data is given to one specific instance of a view.
<p> Based on the above, the solution appears complete. But an element is missing: how do we specify/implement the alternate course of action when an invalid token is detected. In fact, given the case where the submit button is reclicked, the second request will cause the loss of the first response containing the expected result. The thread that executes the first request still runs, but has no means of providing its response to the browser. Hence, the user may be left with the impression that the transaction did not complete, while in reality, it may have successfully completed.This tip's proposed strategy builds on the Struts framework to provide a complete solution that prevents duplicate submission and still ensures the display of a response that represents the original request's outcome. The proposed implementation involves the abstract class SynchroAction, which actions can extend to behave in the specified synchronized manner. This class overrides the Action.perform() method and provides an abstract performSynchro() method with the same arguments. Below is the example implementation in Java using struts </p>
Eg Code:

<pre>
public final ActionForward perform(ActionMapping mapping,
ActionForm form,
HttpServletRequest request,
HttpServletResponse response) throws IOException, ServletException
{ HttpSession session = request.getSession();
ActionForward forward = null;
if (isTokenValid(request))
{
try {
session.setAttribute(FORM_KEY, form);
session.setAttribute(FORWARD_KEY, forward);
ActionErrors errors = (ActionErrors) request.getAttribute(Action.ERROR_KEY);
if (errors != null && !errors.empty())
{
saveToken(request);
}
session.setAttribute(ERRORS_KEY, errors);
session.setAttribute(COMPLETE_KEY, "true"); }
catch (IOException e)
{
throw e;
}
catch (ServletException e)
{
session.setAttribute(COMPLETE_KEY, "true");
throw e; } }

else {
{
throw it if (e != null) { if (e instanceof IOException) { throw (IOException) e; }
else if (e instanceof ServletException)
{ throw (ServletException) e;
} } context if ("request".equals(mapping.getScope()))
{ request.setAttribute(mapping.getAttribute(), f); }

else { session.setAttribute(mapping.getAttribute(), f); }
(ActionErrors) session.getAttribute(ERRORS_KEY));
session.getAttribute(FORWARD_KEY); }
else {
return forward; }

</pre>

As we can see from the above code that for a valid token the protected action is performed only once ,while the action is being performed any other requests are received then
they are directed to performInvalidToken() method until the action is completed ,this method simply returns an ActionForward named "synchroerror" ,this should lead to a form with a button for continue , this just resubmits without any parameters and nothing happens until action of first form submission is completed .When the action completes, it stores its forward, form, exception, and errors, if any, in the session, and it sets a flag to indicate it has completed. The first request coming after the action completion will get the forward, form, exception, and errors from the session and continue as if it was the first request itself.

==PHP==

The following method is one of the ways of creating a Synchronous token pattern

The below given code needs to be added to ur code

<pre>

<?php
session_start();
$secret=md5(uniqueid(rand(), true));
$_SESSION['FORM_SECRET']=$secret;
?>

Here uniqueid() is used to create Unique ID. Then md5() is used to create 32 character hash of this Unique ID. This unique id is stored in the session for later use. We also need to use a different session variable for each form.

Then we add a hidden field anywhere in the form using the below given code.
<input type="hidden" name="form_secret" id="form_secret"
value="<?php echo $_SESSION['FORM_SECRET'];?>" />

we need to compare the value of the hidden field with the value stored in the session. If the value is the same, that means its the first time. Hence process the form data. Now unset the values stored in this session. now when the user refreshes the page, the code for processing form will be skipped. It can be done as given below

<?php
session_start();
//get the hidden value
$form_secret=$_POST['form_secret'];
if(isset($_SESSION['FORM_SECRET'])) {
if(strcasecmp($form_secret,$_SESSION['FORM_SECRET'])===0) {
/*We need to have the form submission code here
*/
unset($_SESSION['FORM_SECRET']);
}else {
//this is the condition of key which is invalid
}
}else {
//this is the case where is secret key is no there
echo 'Form data has been processed once!';
}
?>

</pre>

==JavaScript==

<p> Java Script uses two methods to prevent Duplicate form submissions .The first method disables the button and the second method uses cookies to prevent multiple submissions.</p>

Eg:

<pre>
a.
<SCRIPT LANGUAGE="JavaScript" TYPE="text/JavaScript">
function formControl(submitted)
{ if(submitted=="1")
{ commentForm.Submit.disabled=true alert
("Thanks for your comments!") } } </SCRIPT>

</pre>
<p>
The JavaScript event that fires this script is the onClick event. You're telling it to disable the SUBMIT button after the button is clicked. At that point, the button value equals "1."
We included a JavaScript ALERT box in this example so that you'll know the form is working.
To tie this JavaScript to our form, we change the form's SUBMIT button to call the JavaScript function. This is done by adding an onClick event to the appropriate INPUT tag, as shown below.</p>

<pre>
<FORM action="" method="post" enctype="text/plain" name="commentForm">
How did you find our site? <input type="text" maxlength="30" size="20"><br><br>
<input type="submit" name="Submit" value="Send Comments and Get a Cookie" onClick="formControl(1)">
</FORM></pre>

<p>The problem with this approach is only Internet explorer supports the disable option ,so it is browser dependent.</p>
<p> Below is another approach in java script using cookies in browser</p>
<pre>
b.

The Below code has to be inserted into head section of our code

<script>  </script>
</pre>

<p>
When a user submits the form, the function sets an identifying cookie. Before the form processes, the function checks to see if there is already a cookie set. If not, the form handles the submission as normal. If there is a cookie, the user gets an alert box that says "You've already submitted your answers" and the form submission is blocked.
This is a good, cross-browser way to avoid duplicate submissions, but we have to be careful that user's browser must accept cookies and have JavaScript turned on for this method to work.</p>

==ASP.NET==

<p>
Here is an implementation in ASP that prevents duplicate form submission. In this implementation, we consider two ways of avoiding this problem. One is the Unsafe button method, where the button does not vanish after the user clicks the button. But at the same time does not consider two or more consecutive clicks, if done within a specified period of time, as a different request from the orginal one. The other method is the safe button method where the button vanishes after the button is clicked once and returns only after the request has been completed or timed out.</p>

<pre>
<%@ Page Language="VB" %>
<script runat="server">
Dim counter As Integer
Sub Page_Load()
If Session("counter") Is Nothing Then
counter = 0
Else
counter = CInt( Session("counter") )
End If
If IsPostBack Then
counter += 1
Session("counter") = counter
End If
Label1.Text = "Counter = " & counter.ToString()
SafeButton.Attributes.Add("onclick", "disableButton();return true")
End Sub

Sub Process_Click(sender As Object, e As EventArgs)
Dim i As Long
' 2-second delay
Dim endTime As DateTime = DateTime.Now.AddSeconds(2)
While DateTime.Now < endTime
End While
Label2.Text = "Finished @ " & DateTime.Now.ToString()
End Sub

Sub Button2_Click(sender As Object, e As EventArgs)
Session("counter") = 0
Label1.Text = "Counter = " & Session("counter").ToString()
End Sub

</script>
<html>
<head>
<script language="javascript">
function disableButton()
{
document.form1.SafeButton.style.visibility = "hidden";
}
</script>
</head>
<body>
<form runat="server" id="form1">
<p>
<asp:Label id="Label1" runat="server">Label</asp:Label>
</p>
<p>
<asp:Label id="Label2" runat="server">Label</asp:Label>
</p>
<p>
<asp:Button id="UnsafeButton" onclick="Process_Click" runat="server" Text="Unsafe Button"></asp:Button>
</p>
<p>
<asp:Button id="SafeButton" onclick="Process_Click" runat="server" Text="Safe Button"></asp:Button>
</p>
<p>
 <asp:Button id="Button2" onclick="Button2_Click" runat="server" Text="Clear Counter"></asp:Button>
</p>
<span id="span1"></span>
</form>
</body>
</html>
</pre>

<p>
As explained earlier, the Unsafe button allows users to click on submit multiple times. But clicking on the button again doesnt do anything, a two-second delay has been put into the button handler to emulate the time that a back-end process might take. So unless that time is up it doesnt effective count as a click.</p>
<p>
Even for the Safe button the same process runs. But in this case as soon as the button is clicked, it disappears, preventing you from being able to click it again until the processing (postback) is complete. This ensures that multiple form request is not sent by completely taking out the submit button. </p>

==Ruby On Rails==

Ruby on Rails uses the Submit button disabling method to prevent Multiple form submissions .It uses the submit_tag option .Below is the code that demonstrate this

<pre>
submit_tag "Submit", :disable_with => "Saving..."
</pre>

This adds behavior to the submit button to disable it once clicked, and to display "Saving..." instead of "Submit".

==Conclusion==
<p>
As illustrated in the above wiki, various languages handle the problem of multiple form submission either by client side or server
side methods. Server side handling is more reliable as some web browsers do not support the disabling of button feature. Synchronizer token pattern is best solution as illustrated in Java .In most languages, for server side handling, a token is set once on submission and compared again on resubmission to check for duplicates ,this prevents the data from being inserted again into the database. Some websites just pop message to user to wait until action is completed. Overall Java script is best way to handle duplicate form submission </p>

==References==

<p> Below are some of the references for further reading </p>

<p>http://www.javaworld.com/javaworld/javatips/jw-javatip136.html?page=1</p>
<p>http://forums.asp.net/t/447620.aspx?PageIndex=1</p>
<p>http://drupal.org/node/69048</p>
<p>http://phpsense.com/php/prevent-duplicate-form-submission.html</p>
<p>http://forums.techarena.in/software-development/1149257.htm</p>
<p>http://www.stackoverflow.com</p>