Whitespace and Commenting

Whitespace and Comments in Software Development

Key Concepts

Whitespace for easier code review	Indenting and blank lines visually organizes source code to help other developers understand and modify your code
Commenting for understandability	Adding comments help others understand important and non-obvious code

Terms

Term	Meaning
Bottom-Up Design	A design process that starts by creating and testing each part of the algorithm's functions, then creating the main function to use the parts.
Comments	Text explaining the meaning of lines or section of source code so that people other than the coder can understand what the code does.
Debugging	A development tool and/or practice used by a software developer to find and fix errors in a program. There are many tools and practices available to choose from depending on the situation.
Design	A process used to plan and implement a program's source code.
Functional Error	A program error caused using the wrong function or data. The program may run to completion or stop with run-time error.
Program Flow Error	A program error caused by missing instructions or instruction executed in the wrong order. The program runs to completion, but produces the wrong output or result.
Syntactic Error	a program error caused by misspelling an instruction or failing to use a function correctly. The compiler/assembler fails to build the program or execute it.
Top-Down Design	A design process that starts by creating and testing the main section of the program to ensure it executes an algorithm in the correct order, then the details of each part of the algorithm are created and tested.
Whitespace	Indents and blank lines in source code used to make code more readable for humans.

Introduction

Use of formatting of source code will make it easier to understand and updates. Including comments adds another level of built-in help for future updates.

These elements are your code are purely for humans. Compilers and assemblers ignore these parts of the code when generating the executable. As a result, it will not make the final program any larger.

Whitespace

Using blank section or lines in source code makes it more readable for others. It is a way to visually group and align instructions into understandable groups

LC-3 Whitespace Examples

Indenting

Use Space or Tab indents in code shows how code it organized within a construct like a for-loop. It is visually obvious that code indented run inside the loop and code that is not indented is outside.

for(int i = 0; i < 10; i++){
  myArray[i] *= 2;
  myArray[i] += 1;
}
System.out.println("All values updated");

It is visually obvious that each array elements are doubles, the increments by 1 inside the loop.

Blank Lines

Use blank lines to group associate code. This will make it visually easy to see that several line of code exist for some associated purpose.

let sum = 0;
let count = 0;

for (let i = 0; i < 10; i++) {
  if (myArray[i] > 0) {
    sum += myArray[i];
    count++;
  }
}

let average = sum / count;
console.log(`Found ${count} positive numbers with an Average of ${average}`)

The blank lines in this code separate Initialization, Processing Loop, and Output

True/False

Use of whitespace helps developers understand the program

True	False

True/False

Assemblers/Compilers include whitespace in the executable

True	False

Comments

Comments are included to help other developers understand the organization and important parts of the code. This will help simplify future updates.

LC-3 Commenting Examples

Function Comments

An overall description of the code helps developers understand the big-picture purpose of the program. Block and Inline comments will clarify particular sections.

/**
 * This program reads thru an array, and calculates the count
 * and average for all positive values
 */

let sum = 0;
let count = 0;

for (let i = 0; i < 10; i++) {
  if (myArray[i] > 0) {
    sum += myArray[i];
    count++;
  }
}

let average = sum / count;
console.log(`Found ${count} positive numbers with an Average of ${average}`)

Block Comments

Adding a comment to the beginning of a block can help other developers understand the purpose of group of code.

/**
 * This program reads thru an array, and calculates the count
 * and average for all positive values
 */

// Init variable for results
let sum = 0;
let count = 0;

//Loop thru array looking for positive values
for (let i = 0; i < 10; i++) {
  if (myArray[i] > 0) { //Test for Positive
    sum += myArray[i];
    count++;
  }
}

//Calc and report results
let average = sum / count; //Calc average
console.log(`Found ${count} positive numbers with an Average of ${average}`)

Inline Comments

Adding a comment to the end of a single line of code helps make clear what the line does.

/**
 * This program reads thru an array, and calculates the count
 * and average for all positive values
 */

// Init variable for results
let sum = 0;
let count = 0;

//Loop thru array looking for positive values
for (let i = 0; i < 10; i++) {
  if (myArray[i] > 0) { //Test for Positive
    sum += myArray[i];
    count++;
  }
}

//Calc and report results
let average = sum / count; //Calc average
console.log(`Found ${count} positive numbers with an Average of ${average}`)

True/False

Adding good comments to your code now is likely to help you in the future

True	False

Conclusion

Using whitespace, troubleshooting and modifying code (by you or another developer) can be easier as code is visually organized in groups and blocks.

Adding comments that describe overall function and specific important sections will also help with understanding and modifying the program.