Whether you are a pack hunter or a lone wolf, documentation is at the essence of your code. Do you not agree that code written without proper documentation is like a text in Hebrew? Because we all know, as the scope of the program grows, it becomes impossible to remember the details. That is why all seasoned programmers assert that documentation is the secret recipe differentiating the great from the good!
While working in a team, the variables and functions you encode need to be accessed by others. Your fellow mates may use your work in later versions to cope up with new demands. Untidy cryptic commands will leave them scratching their brains for no reason!
Well, if you are a solo contributor and know your code like the back of your hand? But what if you need to review a part of the code sometime after six months? Clutter of countless variables and myriad functions will send you haywire! Hurrying forward without proper documentation is like being penny wise pound foolish.
You must have now realized that documentation of paramount importance. Here are three tips to remember while documenting your code-
1) The Header- Place a prologue at the beginning of each section. Do include details like data used, purpose, functionality and changes made to the main program. Never forget to add the changes made to the global variables! Write in brief the logical flow and the algorithm. Make the information as lucid as you can wherever complex logic is involved.
/**** HEADER
* purpose of function-
* returns and error codes-
* business logic-
* Additional notes-
****/
2) Body- Nicely indented, commented code is easy to debug.
So keep documentation short and sweet-simple yet descriptive. While including crucial details is indispensable, You do not want to be a parrot with comments like
count++; /*increase counter by one*/
3) Naming Variables- The information the variables hold must be evident from their name. You must have experienced that two identically named variables lead to silly errors. While labelling the functions, be careful not to hinder their black-box treatment.
/*correct*/
RandomNumberGenerator();
Random_Number_Generator();
/*incorrect*/
randgen();//unclear wording
StochasticStatsticalRandomGenerator();
/*no black-box treatment of function*/
Thus we conclude that a code without documentation is an unsharpened knife!!
Top comments (1)
The best documentation is the one that doesn't start with // - trying to express ideas through code should be the focus, I think contextualization should be somehow guaranteed in advance.