Internal Documentation - IDOC Requirements

Every File Will Contain Five Comments

Line 1. Description of the Class - What it does. Could take up more than one line.

Line 2. Programmers Name - Your Name

Line 3. Project Name (namespace)

Compiler will put underscores where you have spaces in the project name. Either is appropriate for the comment.

Line 4. Date the file was Created

Line 5. Contributors - People that helped. If none helped you MUST put NONE.

Main Methods IDOC

Required commented sections of code

// Description
// Declarations
// Input
// Processing
// Output

Comment ALL end braces and add a ReadKey() statement as the very last statement in Main.

 

Classes Not Containing a Main IDOC

Commented Sections of a Class

// Instance Variables

// Constructors

// Properties

// Mutators

// Helpers

Comment ALL end braces

Magic Numbers

In programming, a "magic number" is a value that should be given a symbolic name (Constant) , but was instead slipped into the code as a literal, usually in more than one place. In programming, a magic number is a numeric value that is used directly in the code. 

One of the most important aspects of code quality is how it conveys intention (readable).  We should not use the magic numbers in programming because it tends to make the code difficult to understand and maintain. It also hides the intention so the use of magic numbers should be avoided. 

Magic Numbers must be constants OR the magic number must be commented.

Magic Numbers in formulas can be used if commented.

Example - this statement has three magic numbers. No reason to declare constants for each.

Comment the conversion. This makes way more sense than creating constants.

 

Updated: Wednesday, June 8, 2022 4:28 PM