[thelist] Documentation

[Burhan Khalid]

On the subject of documentation :

One thing that I learned from my COBOL professor in college, and something
that has served me well is the use of a data dictionary. People have
different ways of implementing this, but it is basically a reference for all
your variables. I usually put it at the top of my main code file (or
index.php, or the file that contains main() for C/C++). This is helpful,
especially if down the line someone else has to read your code and decipher
it. Not everyone uses descriptive variable names, and it certainly beats
trying to figure out what x12, gtx, and vrb mean.

Here is an example (for C++) :

/*

  Data Dictionary (DD)
  Compiler : MSVC6.0
  Platform : Windows XP
  Compiled : 02/08/2002 3:13 PM CST

  Name       Type        Comments
  -------------------------------------------
  un         String      User Name from Input

  ....


*/

Another good practice (this is mentioned in several programming books) is
appending the type abbreviation to a variable name. Somewhere I heard that
this sort of technique actually has a name, but it escapes me right now.
Here is an example :

strUN (string)
intX  (integer)
lngX  (long)

and so on.

Hope this makes us all more coder-friendly coders :)
Regards,
Burhan Khalid

_________________________________________________________________
Get your FREE download of MSN Explorer at http://explorer.msn.com/intl.asp.