HowTo Write Clear Source Code
I am starting to write this thread in order to hope seeing in the future clear and understandable source code in the different programming sections. Also I am writing this for the new programmers who want to learn how their code can be more understandable as well as for the experience programmers, despite the fact that I am pretty sure they know these tips, who want to make perfect their code.
The following examples are in C but , I want to believe that even non-C programmers can understand the code.
So let's start:
√ Write your program structrure by using empty lines
Use them when you use brankets for example: in functions/procedures , loops or if statements
Code
int main()
{
int i=123;
if ( i != 123 )
printf("Impossible");
else
return 0;
}Ofcorse you can write it even more detailed like this:
Code
int main()
{
int i=123;
if ( i != 123 )
{
printf("Impossible");
}
else
{
return 0;
}
}√ Add comments to your source code
Believe me , your code will much more understandable when you are writing many lines of code. Also , if you code has bugs and you are trying to spot and fix them , the comments can help you and lead you to the success. Finally your code will be undestandable by third persons who may try to read your code and follow your mind.
Example:
Code
if (key_code == 8) /* if key_code = [DEL] then ... */
{
/* Do the job */
....
}It is much easier to remember that this if statement checks if the key_code variable is the Delete Button (eg: Keylogger).
Although we shouldn't overdo it like here:
Code
/* Now we increase the ammount of the variable The_number_of_cats by 1 */
The_number_of_cats = The_number_of_cats + 1;This will be very tiring if we start to read a bunch of these comments. We aim to comment the work of our algorithm , even comment the command use , without useless comments.
√ Remember to define variable names that reminds you the use/purpose of the var
In many languages you can define constand variables and use them instead of 'naked' numbers. ( In C language you can use the "#define" command in order to achive this.
Code
change_background_color( 4 );You must be wondering here : "What Color is the number 4 ?"
Code
/* screen.h
* Constants and prototypes for the screen driver */
#define BLACK 0x00
#define BLUE 0x01
#define GREEN 0x02
#define CYAN 0x03
#define RED 0x04
#define WHITE 0x0F
int main()
{
change_background_color( GREEN );
return 0;
}As you can see here , it is obvious that we change the color to green.
√ Do not use long variable names
Just imagine if you have to use it many times in your code something like this:
Code
int THE_TOTAL_NUMBERS_OF_CATS_IN_THE_STREET = 0;This can be very tiring when you read/edit the source code. Instead of this , you can use something like:
Code
int total_cats = 0;or even better:
Code
int cCats = 0;√ Do not be carried away to optimize your source code with the result to loose your clear code
If you found out a new way (better algorithm) to do some work it is ok to write it , but you should to write/edit it so I will look clear and before that, comment the code by giving a generic idea on that it actually does.
Code
/* Fib(int value): Finds a given value in the array */
int Search(int *array, int value)
{
//...
}A great idea is to use the Hungarian Notation for the Variable Names: http://en.wikipedia.org/wiki/Hungarian_notation
Links
GNU Coding Standards - Wikipedia, the free encyclopedia
Programming style - Wikipedia, the free encyclopedia
Writing clean code
Six ways to write more comprehensible code
Any Feedback is Welcome . If you would like something to be fixed/modified feel free to post your suggestions :)
