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

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

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

What is iostream.h in C++ Programing Language ?

In C++ programing language, all header files end with .H extension. In standard C++, all devices are accessed and used as a file.  One such header file is iostream.h in C++ programming language. In this, all input and output devices are treated as files.  Let's quickly look at what are the input and output devices mean in C++ program.  Standard Input Device - Keyboard  Standard Output Device   - Monitor  Standard Error Device - Screen or monitor In C++, input and output are not defined within, and are implemented with the help of a component of the C++ standard library which is I/O library.  A file is read simply as a stream of bytes at the lowest level. But at a user level, a file consists of possibly mixed data types which can be characters, arithmetic values class, objects etc.  What are the predefined streams in I/O Library? As discussed above there are input, output and error library in c++, they have some predefined streams objects as well w...
Read more