CSC/ECE 517 Fall 2009/wiki3 14 rd
Principle of Self-Documentation
Introduction
A good code can be defined as a code that has a good structure and design, correct algorithm used and a good flow to the program. Good code is not replete with question mark colon operators and pointer arithmetic, or at least not when the code doesn't need to be optimized to save a few seconds every few months of operation. The algorithm may be too complex and function names may be esoteric . This makes readablility of the code an issue. Thus the defenition of a good code involves a good self documenting sturcture and invloves many comments to aid the user or developer in understanding the code .
Self-Documentation
Self documentation of the code invloves using two methods
- 1. Coding style
One of the major goals when embarking on a development project is to structure the application such that the code documents itself. Thus if all the comments disappeared , the code should still be understandable to the developer
- 2. Commenting
To make the code completely understandable the use of good code documentation is not enough . There is the need to give explanation of the working and the flow which may not be easily derieved form the code itself .Explanation of an algorithm can only be done with the use of comments.
Coding Styles
The biggest concept of self documentation is the naming itself .The is basically two rules for that one has to follow in order to ensure that the code is self documenting .
- If it looks like a cow and acts like a cow, call it a cow.
- Once you call it a cow, make sure you always call it a cow.
In other words , the naming should be as meaningful as possible and the developer should stick to it trying not to step out of convention. The abbreviations used in the code should also be those that are commonly accepted .
naming message as msg and sticking to it is a good coding style
naming message as mesg,msg,mess,msge throughout the code will make understanding of the code difficult
Methods
When trying to name a method , try to describe the intent in the name itslef . This enables the developer to understand the code and the use of the function call in the program.
user.GetID(); user.Get(); product.GetAvg();
Understanding the method calls by just looking at the code is difficult .The reader to actually drill into the logic to determine what the method actually does.
user.getcustomerID(); user.Getnextcustomer(); product.GetAveragePrice();
The method calls makes for explanation of the logic more clear . The function names explain themself what the call invloves.
Another advantage to implementing this type of specific naming in your code is that it can give you an excellent heads up when a method is trying to do too much.When you are attempting to name a method and you find it difficult because of the scope of the method you should definitely examine it and see if you can break it up into smaller more specific pieces.
Variables
Simliar to the principles for naming methods, name your variables explicitely as to what they accomplish. The worst case scenario of this would be using a variable "d" which tells me absolutely nothing. Slightly less harsh would be using "dt, dte, or date". What is most beneficial to the reader is using a name like "CurrentDate" or "MeetingDate".
Another example is the use of i,j in looping sturctres .
for i = 1 to 7
The code suggestst that there is looping structure here ,but nothing more
for dayInWeek = 1 to NUM_DAYS_IN_WEEK
Thus by the use of specific variables and prameters the loop structure is now clear in terms of its use in the code.Although the coding style becomes more verbose , it will aid in better understanding of the code even for the developer when he returns to add or extend the code .