Kindly ensure that the code is properly commented. There should be comments, if not with each statement, then at least with each block of code or loop. For instance a file or a major block of code should begin with purpose and description of the code:
Info | ||
---|---|---|
| ||
Perhaps we should be stressing the use of perldoc also? |
No Format |
---|
########################################## #Get TULIP responsive host distances between Guthrie and Tulip # The Input gives the IP addresses and distances of responsive TULIP hosts # Example: # 30.87.34.2,8551.236157 # 140.181.96.29,18488.23791 # 203.181.248.234,5148.805353 # 203.181.248.241,5148.805353 # 134.160.224.254,16684.70444 # 136.142.111.46,1685.3686 # Returns: # A hash associated with the IP addresses with the value distance, |
Each subroutine should also have a brief description like:
No Format |
---|
########################################### #Executes synack to a target, and parses the results to provide # 0 if successful or -1 otherwise. If unsuccessful then prints #an error message to STDOUT. # The target is provided in the argument, i.e. $_[0] #Example of Unix synack output that is parsed by this sub: #SYN-ACK to dns1.ethz.ch (129.132.98.12), 4 Packets # # connection for seq no: 0 timed out within 1.000 Secs # connection for seq no: 1 timed out within 1.000 Secs # connection for seq no: 2 timed out within 1.000 Secs # connection for seq no: 3 timed out within 1.000 Secs # # Waiting for outstanding packets (if any).......... # # # ***** Round Trip Statistics of SYN-ACK to dns1.ethz.ch (Port = 22) ****** # 4 packets transmitted, 0 packets received, 100.00 percent packet loss # round-trip (ms) min/avg/max = 0.000/0.000/0.000 (std = 0.000) # (median = 0.000) (interquartile range = 0.000) # (25 percentile = 0.000) (75 percentile = 0.000) sub synack { my $target=$_[0]; if($^O=~"linux") { my $success=0; ... |
It is always good to maintain a change history. It is of great help when applications are in production environments and someone needs to make a slight modification. So include a version number and date and the major changes made for this version, comment older version numbers and their descriptions, for example:
No Format |
---|
#my $version="3.73, 3/2/06, Les Cottrell"; # Replaced use of uname with $^O to improve tainting # Increased the debug output to show the pwd #my $version="3.74, 5/8/06, Les Cottrell"; #Enabled pings from onsite to onsite my $version="4.0, 5/13/06, Les Cottrell"; #Added synack for SLAC |
Note | ||
---|---|---|
| ||
We are in the process of shifting everything into CVS. Putting versioning into the code is ugly and not very useful. |
The rule of the thumb is to keep this thing in mind while coding.
"How would it feel if someone provided me a similar code and I had to make one small
change and it took me a whole day just to point out that one line!! So if I don't want to mess up someone's day, I better put useful comments."