Comment Lines:
In computer programming, a comment is a programming language construct used to embed programmer-readable annotations in the source code of a computer program. Those annotations are potentially significative to programmers but typically ignorable to compilers and interpreters. Comments are usually added with the purpose of making the source code easier to understand. The syntax and rules for comments vary and are usually defined in a programming language specification (see the syntax of comments in various programming languages).
Here we are going to see the general way of writing comment lines in all programming languages.
Lets Start with the Higher level and move to the lower
1.Writing comments for Packages:
The comment line for Package must contain Package name, Application Name,author name, copyright of that package, version number and large description about the package
Package Name: This denotes this comment belongs to which package.
Application Name: Name of the application for which this package has been created.
Author Name: Author who created this package. This tag will be useful in future when someone gets a doubt in the code so that he could contact the author.
Copyrights: This shows to which this package belongs to. IN special word it can be said as license.
Version: Carries version number of the package. On creating the package there is no need of explanations in notes section. But if there is any updates like adding class or changing the variables or any thing, the version should be increased. Writing notes helps in keeping track of the changes that are made.
Description: Describes the package
/**
* @package: Sample Package
* @application Name: Sample Application
* @author: Pavofeathers
* @copyrights: Pavofeathers The true technology @ All right received
* @version : 1.2
* This package is used to get all the users information and store in it in database. The database used in this package is User and the table that stores the generated tables are usersinfo, payroll and etc. this package implements the CustomDatabase package to get the database connections and for commit and rollback of the database
**/
/**Notes
* @version 1.1: The class named UserRegistration got changed. i previous version they set the employee name is uniques but in this 1.1 version the employee id became an unique ID
@version 1.2: The RequestUser class function named getUser() function methodology got changed because in previous version it not gets number of worked hours but in new it got added.
*/
/*@interface Name: Sample Interface
@ application Name: SAmple Application
@ author name: Pavo feathers
@copyrights: Pavofeathers The true technology
@version : 1.5
Elaborated description about Interface
*/
/*Notes -- as same as package comment
*/
3. Writing comments for the Classes
/*
@Class Name: Sample Class
@application Name: SAmple Application
@ author name: Pavo feathers
@copyrights: Pavofeathers The true technology
@version : 1.3
Elaborated description about Class
*/
/*Notes -- as same as package comment
*/
4. Writing comments for functions
This comment must contain function name, parameters passed and the return type, returning value description, exceptions and function description.
/*
@function Name: sampleFunction()
if the function is private there is no need of so general description technical description itself enough. In case the function is public u must write the description in general even the person without programming language could understand what's happening inside the function.
@param: arg1 - detailed description abt the parameter
@param: arg2 - detailed description abt the parameter
@param: arg3 - detailed description abt the parameter
@return returm type where it will return and what its use
if the parameter is BOOL the description want to be like this
<li>true</li> if the returned value is true what it does or means
<li>false</li> the returned value is false what it does or means
@exceptions: What are the exception that can be expected from this function and how you handling those exceptions.
*/
BOOL sampleFunction(int arg1,float arg2, double arg3)
5. Comments for variables:
Writing comments for all the variables is not must but advisable. But writing comments for public variables and global variables are must.
The comment for public variable must be easily readable and understandable.
// This variable is used to count number of users registered for the lunch in
//office. This count will be assigned from the table user info
public int userCount;
6. Comments for the loops
Writing comment for the critical loop is very important. In case our project overtaken by some other programmer. Even he is expert in logical things he cant easily recognize what we written there.
/*
* This loop runs until it gets the random player(random number) and also avoids the player that already selected
*
*/
//this while runs upto selecting the player
while (!playerAlreadySel) {
randomNumber=random()%numberOfPlayers;
if([playedPlayers count]<=0)
break;
// this for loop runs according to the number of players already played
for(int i=0;i<[playedPlayers count];i++)
{
// this if loop checks whether the repetition of already selected player
if([[players objectAtIndex:i] isEqualToString:[[NSNumber numberWithInt:randomNumber] stringValue]])
{
playerAlreadySel=NO;//'NO' BOOL assigned to check the random player newly selected were already played or not
break;
}
else
playerAlreadySel=YES;
}
}
I think maximum I have covered the places where the comments should occur.
Don't worry the Compiler ignores the comment text while compiling. So it won't occupy the memory in your application.
Few other useful links regarding writing comments
Syntax of comments in various programming languages
Docstring, a specific type of comment that is parsed and retained throughout the runtime of the program.
