To Documents

Source Code Documentation

• An apostrophe (') marks the beginning of a comment line.

• Each source code file should contain a header with the project name, author, and submission date.

• Comments should be written at the same time that the code is written. Writing the code first and adding the comments later is unprofessional.

• Use blank lines to separate the code into logical sections.

• Don't over do decoration of comments such as
  '***************************
  '* Close the output file.  *
  '***************************

• Use the imperative mode to express comments. This keeps the comments short.

• Comments should be an alternative to reading the code. They should not parrot the code.

  Do this:
  ' Add odd numbers from 1 to 99.
  sum = 0
  For value = 1 To 99 Step 2
      value += i
  Next

  Do not do this:
  ' Add i to the value of sum.
  sum += i

• Comments are meant to supply the following information:

  Who	Who wrote the source code; who made modifications?
  What	What is the code supposed to do?
  When	When was the course code written; when were the modifications made?
  Where	Where should the reader look for extra explanation?
  Why	Why was the code written the way it was?

• Use meaningful variable names.

• Single letter variable names are only allowed for loop indices.

• Variables should rarely be more than twelve characters long.

• A logical statement should not contain more than four line continuations.

• Use a consistant capitalization style for variable names, for example:
  
  Camel Style: numberOfCustomers
  Camel Style: NumberOfCustomers

• Avoid multistatement lines like this:
  count = 0 : totalIncome = 0