CE 311K Computer Methods Comments and Formatting in Code

The first and most important trait of a program is that it works. This is obvious. But what separates a working program from a well-written program is readability. Commenting and formatting style are components of well-written programs. This handout explains how commenting and formatting style should be used in your programs.

Comments

Comments should be used liberally throughout the program and the comments should be specific, concrete explanations of the task being performed. For example, saying “Loop” as a comment before a loop is not sufficient. It is obvious to an outside reader that a loop is being performed. Be more specific by saying “This loop estimates the value of cos(x) for m terms,” or something similar. Comments do not need to be long or overly detailed. The goal is to communication to a reader who is unfamiliar with specific code you are writing, yet has a working knowledge of VB, what each task in the program is doing.

Poor Commenting ‘Loop Do While (n < m) [statements] Loop

Good commenting ‘This loop find the value of cos(x) by adding m terms Do While (n < m) [statements] Loop

Formatting Style

Formatting style primarily refers to the indentation of lines. There is a universally accepted way of formatting If/Then statements and Loops within programs. No matter what language (VB, Fortran, C++), programmers use this formatting style. Thus, if you want to share your code with others, it is important to follow the formatting style. The point isn’t to be picky, but rather to allow others to read and understand your code as quickly and easily as possible.

Poor Formatting Style Sub main() Do While (n < m) If n = 1 A = n + 5 Else A = n + 4 EndIf n = n +1 Loop End Sub

Good Formatting Style Sub main() Do While (n < m) If n = 1 A = n + 5 Else A = n + 4 EndIf n = n +1 Loop End Sub

Please follow these guidelines for commenting and formatting the programs you create for lab and homework assignments.