guide for documenting your code
jbwyatt.com

Code Readability

If you want me to look at code - COMMENT! - so I (and YOU) know what you're TRYING to do. When you comment, you are EXPLAINING the CODE to YOURSELF as well as others.

If you write great code, but the code is unmaintainable, you are a liability. 50-75% of a software system's cost is consumed by maintenance which includes fixing problems, adapting code to new environments and adding functionality.

The readability of the program directly affects maintainability. It takes more time to write maintainable code, but there is a large ROI. Adhere to these guidelines - significant points will be deducted if you do not.

"I just began working on a project that is pretty much a rewrite of an entire system because of sloppy, poorly documented code. Please stress to your students the importance of good documentation. It is nice for the person who has to go through all of it!"
-- message from a former student, Feb, 2010

Program Coding Standards: C#, C++, JavaScript, Assembly

Program Header: Always has THREE components.

  1. Identification:   Name / Date / Class
  2. Purpose:   Why is the program being written? What problem does it solve? A few sentences or a paragraph here.
  3. Algorithm / Overview:
    The steps you are going to take to solve the problem. Put some details here!.
    Write in bullets - not prose-style rambling... This is your plan of attack!

Body: Make it readable with these FOUR components

  1. Meaningful Names: variables, constants and functions.
    Names should reflect the purpose they have. A person's age should be stored in "age", not "x".
  2. Indent: indent the code affected by loops and if/else statements.
  3. White Space: Use both horizontal and vertical white space to make code readable.
  4. Comments: explain WHY things are being done. Don't repeat the obvious. Give the reader insight.

Additional Functions / Methods:

  1. Purpose: Simple statement of what the function/method does AT THE TOP
  2. Indent, Naming, White Space, Comments
  3. Author (if code is in a separate file)

Examples:
C# Console: GlazerCalc.cs   |   C# Windows: FF.cs   |   C++ Console: Metric.cpp   |   Assembly: Template.asm   |   Web JavaScript: js

Program Coding Standards: HTML, CSS

Program Header: Always has Author and Page Description

  1. Identification:   Name / Date / Class
  2. Purpose:   Why is the page being created? A few sentences or a paragraph here.

Body: Make it readable with these THREE components

  1. Indent: indent the html and css to reflect the organization.
  2. White Space: Use both horizontal and vertical white space to make it readable.
  3. Comments: use to explain BLOCKS (divs or headers or paragraphs) or section of CSS.

Examples:   Web HTML: example.html   |   Web CSS: base.css

valid xhtml 1.0