Skip to main content

Why it is important to write Comments


There are two reasons to write a comment:

1. to improve the readability or maintainability of the code; or
2. to provide text for a documentation tool.

If you can’t do either of these, don’t write a comment. Experienced programmers prefer to read and understand code without the aid of comments. They know, from bitter experience, that the code is a more reliable guide to what the program actually does.


However, you will sometimes come up with tricky code after thinking deeply about a problem and
rejecting alternative solutions. In this case, it may help the maintenance programmer (who might
be you, six months later) by explaining why you write the code in a particular way.
The only realistic way of keeping documentation consistent with code is to write the documentation
as part of the code and then extract it using a tool such as Doxygen .Note the use of Doxygen markup such
as \b, \param, and \return. If you use a tool such as Doxygen, use it consistently: provide
documentation for all visible entities in a way that will help others to use the library, or whatever it
is, effectively.

Labels:

Popular posts from this blog

C++ Program to find the sum, difference, product and quotient of two integers

#include <iostream.h> #include <conio.h> void main() {   clrscr();   int x = 10;   int y = 2;   int sum, difference, product, quotient;   sum = x + y;   difference = x - y;   product = x * y;   quotient = x / y;   cout << "The sum of " << x << " & " << y << " is " << sum << "." << endl;   cout << "The difference of " << x << " & " << "y <<  is " << difference << "." << endl;   cout << "The product of " << x << " & " << y << " is " << product << "." << endl;   cout << "The quotient of " << x << " & " << y << " is " << quotient << "." << endl;   getch(); }
Read more

Program of virtual piano

//////////////Tested And Created By C++/////////////////////////////// #include<stdio.h> #include<dos.h> #include<conio.h> #include<stdlib.h> #define SHOW 1 #define HIDE 2 union REGS input,output; class piano {  public:int BIGKEY,MIDKEY,back,border;     piano()//init constructor     {         BIGKEY=15;         MIDKEY=1;         back=7;         border=15;     } }color; void drawpiano(int x,int y); int check_xy(int x,int y); void BOX(int c,int r,int c1,int r1,int col); int initmouse(); void setupscreen(); void pointer(int on); void restrictmouse(int x1,int y1,int x2,int y2); void check_keys(int x,int y); void getmouse(int *button,int *x,int *y); float freq[7] = {130.81, 146.83, 164.81, 174.61,196, 220, 246.94 } ; int n=0,a=4,backcolor=2,exitcode=1; void showbar(int t) {  if(t>65) t=65;  if(t<1) t=1;  textcolor(15);  for(int q=0;q<=t;t++)  {     gotoxy(3+q,4);     cprintf("Û");  } } void main() {  int
Read more

Putimage function in c

putimage function outputs a bit image onto the screen. Declaration:- void putimage(int left, int top, void *ptr, int op); putimage puts the bit image previously saved with getimage back onto the screen, with the upper left corner of the image placed at (left, top). ptr points to the area in memory where the source image is stored. The op argument specifies a operator that controls how the color for each destination pixel on screen is computed, based on pixel already on screen and the corresponding source pixel in memory. c smiling face animation This animation using c draws a smiling face which appears at random position on screen. See output below the code, it will help you in understanding the code easily. C programming code #include<graphics.h> #include<conio.h> #include<stdlib.h>   main() { int gd = DETECT, gm, area, temp1, temp2, left = 25, top = 75; void *p;   initgraph(&gd,&gm,"C:\\TC\\BGI");   setcolor(YELLOW);
Read more