There are two big problems with writing programs. First, you have to worry about getting the program to work. Second, you'll probably need to fix and modify it later. To solve both types of problems, you have to understand how the program works in the first place. To understand how a program works, programmers have to explain
What problem the program is trying to solve
How the program is designed
How each part of the program works
In the early days when programs were small, programmers could figure out all the preceding questions by studying the source code of the program. When programs got bigger and tackled more complicated problems, programmers could no longer understand how a program worked by examining the source code. That's when programmers were forced to start writing additional explanations, or documentation. By studying this documentation, other people could understand how a program works without trying to decipher the actual source code of a program.
One of the first attempts at explaining how a program worked was by making the source code more understandable by using high-level languages, like BASIC or Pascal, to create self-documenting code. So rather than try to decipher cryptic code like
SECTION .data msg db "It's alive!!",0xa; len equ $ - msg
SECTION .text global main main: mov eax,4; write system call mov ebx,1 mov ecx,msg mov edx,len int 0x80 mov eax,1 system call mov ebx,0 int 0x80
You could replace the preceding assembly language commands with a shorter, more descriptive high-level language command like this:
PRINT "It's alive!"
Such self-documenting code helps explain what a single line of code does, but doesn't necessarily tell you how the entire program works as a whole or what problem the program even solves.
Rather than rely on "self-explanatory" language commands, programmers started adding explanations directly into the source code itself by using comments.
A comment is nothing more than text, embedded in the source code. To keep the compiler from thinking a comment is an actual command, every comment needs a special symbol in front of the comment, such as
REM This is a comment in BASIC ' This is another comment in BASIC // This is a comment in C++ and Java # This is a comment in Perl and Python ; This is a comment in LISP and assembly language
Comments allow you to write short explanations, directly in the source code, that describe what the source code does. Looking at the following code, can you understand what it does?
C = SQRT(A * A + B * B)
Deciphering this code is straightforward. This command multiplies two variables by themselves, A and B, adds the results together, and finds the square root of the sum, which gets stored in the C variable. However, knowing how the command works doesn't tell you what or why this code is doing this. By adding comments to the source code, you can explain this, as follows:
' Calculates the hypotenuse of a triangle (C) ' using the Pythagoras theorem: C2 = A2 + B2 C = SQRT(A * A + B * B)
Even if you don't know (or care) about Pythagoras' theorem, the comments help you understand what the command is calculating.
Warning
Some programmers use comments to insert jokes, profanity, or remarks about their co-workers directly in their source code. Just be aware that other people besides you may need to look at your source code. So if you've laced your program with profanity-ridden tirades against your co-workers, don't be surprised if one of your co-workers finds and reads the comments you made about him, which could be humorous or embarrassing.
You can put comments anywhere in a program because the compiler ignores them anyway. The two types of comments are line comments and block comments.
Line comments appear directly on a line that already contains a command like this:
C = SQRT(A * A + B * B) ' Calculates Pythagoras theorem
The problem with line comments is that they can make source code somewhat harder to read. That's why some programmers prefer putting comments on separate lines like this:
' Calculates Pythagoras theorem C = SQRT(A * A + B * B)
Warning
Comments exist purely for other people to read, so it doesn't matter whether you put them on a line with a command or on a separate line.
To make comments easier to read, use plenty of blank lines and spaces. The following example looks crowded:
' Calculates the hypotenuse of a triangle (C) C = SQRT(A * A + B * B) ' Calculates Pythagoras theorem
By adding blank lines and extra spaces, you can make each comment easier to find and read:
' Calculates the hypotenuse of a triangle (C) C = SQRT(A * A + B * B) ' Calculates Pythagoras theorem
If you need to write several lines of comments, typing the comment character in front of each line can get annoying. As a simpler alternative, many programming languages let you create block comments.
A block comment lets you identify the beginning and end of a comment. So if you wanted to write a comment on two separate lines in C++, you'd have to type the // symbols in front of each line, such as
// Calculates the hypotenuse of a triangle (C) // using the Pythagoras theorem: C2 = A2 + B2
If you created this as a block comment, you could use the /* and */ symbols to mark the start and end of a comment like this:
/* Calculates the hypotenuse of a triangle (C) using the Pythagoras theorem: C2 = A2 + B2 */
No matter how many comments you add, you only need to use the /* and */ comment symbols once like this:
/* Calculates the hypotenuse of a triangle (C) using the Pythagoras theorem: C2 = A2 + B2. The length of the hypotenuse is then used to move a cartoon figure on the screen. */
Warning
Block comments just make it easier to add multiple lines of comments. Programmers often use both line and block comments in a single program like this:
/* Calculates the hypotenuse of a triangle (C) using the Pythagoras theorem: C2 = A2 + B2. The length of the hypotenuse is then used to move a cartoon figure on the screen. */ c = sqrt(a * a + b * b) // Pythagoras theorem
Warning
The comment symbol in one language may have a completely different meaning in another language, so make sure you don't mix them up.
In the curly bracket languages (such as C++ and Java), the curly brackets are used to define a block of commands like this:
int main() { cout << "Hello, world! "; }In Pascal, the curly brackets are used to create block comments like this:
{ Calculates the hypotenuse of a triangle (C) using the Pythagoras theorem: C2 = A2 + B2. The length of the hypotenuse is then used to move a cartoon figure on the screen. }
Tip
To make block comments stand out, many programmers surround comments with additional symbols. So instead of writing a simple block comment like this:
/* This code calculates how many megatons will be needed to blow up at least 75% of the world and throw huge chunks of the planet into orbit around the moon. */
Many programmers emphasize the block comments by inserting extra symbols, such as asterisks, as follows:
/*********************************************** * This code calculates how many megatons will * * be needed to blow up at least 75% of the * * world and throw huge chunks of the planet * * into orbit around the moon. * ***********************************************/
The compiler ignores all these extra symbols and just focuses on the /* symbols to identify the beginning of the comments and the */ symbols to identify the end of the comments.
Rather than surround comments with extra symbols, some programmers use extra symbols in the left margin, such as
/* ** This code calculates how many megatons will ** be needed to blow up at least 75% of the ** world and throw huge chunks of the planet ** into orbit around the moon. */
Every programmer eventually develops a preferred style for writing comments, so be consistent and other programmers will have no trouble finding and reading your comments.
Comments are typically used to explain what one or more lines of code do or how they work. For example, suppose you had the following code:
F = P / (1 + (B * exp(-c * t)))
Looking at this code, you can tell how the computer calculates a result, but you have no idea what result this code is calculating. So you could add a comment that explains what this code does like this:
' This formula calculates the spread of a flu epidemic as a ' a function of time F = P / (1 + (B * exp(-c * t)))
Now that you've identified what the code does, you can use additional comments to explain how it works:
' This formula uses the epidemic model to calculate the ' spread of a flu epidemic as a function of time ' F = Function of time ' P = Current population of a city ' t = Time measured in weeks ' c = Number of people in contact with an infected person ' B = A constant value that can be determined by the initial ' parameters of the flu epidemic F = P / (1 + (B * exp(-c * t)))
Although you may still not understand what the preceding code does, the comments can help you understand what the code does (calculating a flu epidemic) and how it works. Without these comments, the code itself can tell you little about what it does.
Note
There are two schools of thought regarding comments. One school says to use comments liberally to explain both what code does and how it works. The second school believes that if you have to add comments to explain what and how your code works, your code is probably too complicated in the first place. This second school of thought believes that instead of writing comments, programmers should just focus on writing self-explanatory code. Most programmers try to write self-explanatory code and use comments whenever necessary.
Another use for comments is to explain the logic behind your code. For example, if you declared a variable as a Byte data type instead of an Integer data type, you might include a comment explaining why you chose one data type or another like this:
' Declared the "Age" variable as a Byte data type since ' Byte data types only accept values from 0 - 255. Dim Age as Byte
Warning
Use comments sparingly only when the purpose of code isn't obvious. Redundant comments help no one, as the following example shows:
' Calculates interest payments by multiplying the ' principal by the interest rate and the time. Payments = Principal * Rate * Time
If a comment repeats information that anyone could read from the source code, take the comment out. Otherwise, you risk cluttering your source code with useless comments that only make your program harder to read.
Comments can explain the purpose of one or more lines of code, but many programmers also use comments to document entire subprograms, such as
Describing what the subprogram does
Listing the original programmer (along with contact information, such as an e-mail address)
Defining the original creation date and last date of modification
The following code shows how to use a block comment to document a subprogram:
/*********************************************** * Description: * * * * This subprogram calculates the angle needed * * to track and aim a laser for shooting down * * anti-aircraft missiles fired at airplanes * * as they land or take off. * * * * Author: John Smith ([email protected]) * * * * Creation date: January 21, 2006 * * * * Last modified: September 5, 2007 * ***********************************************/
By placing such a descriptive comment at the beginning of every subprogram, other people can understand what the subprogram does and who to contact (blame) without having to examine the source code line by line.
Comments can temporarily ignore lines of code for testing. For example, suppose your program included the following:
Y = log(Y) - (500 + sin(Angle)) X = Rate * exp(X) / Y PRINT "The value of x = ", X
If you wanted to see how your program would work if you eliminated the first line of code and replaced it with a new line of code, you could erase the top line and type a new line, such as
Y = cos(Angle) * Y X = Rate * exp(X) / Y PRINT "The value of x = ", X
Now if you wanted to replace the top line with the previously erased line, you'd have to delete the top line and retype the preceding line all over again. A simpler method would be to comment out the top line and type in a new line, such as
' Y = log(Y) - (500 + sin(Angle)) Y = cos(Angle) * Y X = Rate * exp(X) / Y PRINT "The value of x = ", X
This causes the compiler to ignore the top line (treating it as a comment). Now if you want to "insert" the top line back into the program, you can comment out the second line and remove the comment symbol from the first line:
Y = log(Y) - (500 + sin(Angle)) ' Y = cos(Angle) * Y X = Rate * exp(X) / Y PRINT "The value of x = ", X
The preceding code is equivalent to the following:
Y = log(Y) - (500 + sin(Angle)) X = Rate * exp(X) / Y PRINT "The value of x = ", X
Warning
By commenting out code, you can temporarily ignore code without deleting it. Then you can add the code back into your program by removing the comment symbol rather than retyping the entire line again.
Most source code makes no sense to non-programmers. Even worse, most source code often makes no sense even to the original programmers after they stop working on it.
Many programmers work on a program and understand all the idiosyncrasies and quirks of that program. Then they work on another program and forget how the first program worked. When they return to the first program, the source code can look as alien as trying to read someone else's handwriting. For that reason, software documentation is crucial.
Documentation typically consists of text that's physically separate from the source code. The three types of documentation include
Design specifications
Technical designs
User manuals
Warning
Although software documentation is often treated as an afterthought, it can be a crucial step in completing any program. The key to software documentation is to make it easy to create while still being useful. If you can do that, your software documentation will be a success no matter how much (or how little) time you spend putting it together.
Design specifications
Design specifications list the program requirements so the programmers can understand what problem they need to solve. Unfortunately, projects tend to change over time, so it's common to specify one type of program and then halfway through the project, someone suddenly decides to add an entirely new feature.
Trying to design everything beforehand is like trying to describe the perfect apple pie without even knowing what an apple pie looks or tastes like. Design specifications can help give a project focus, but their ultimate goal is to help programmers create a useful, working program.
Technical design
Programmers use a technical design document to organize how to write the program. This means specifying how the program will work, what programming language and compiler to use, how to divide the program into parts, and assigning teams of programmers to work on each part.
Warning
Technical design documents usually start off being fairly complete and accurate, but trying to design a program is much different than actually writing that same program. Therefore, the design of a program can change as programmers run into obstacles that they didn't foresee ahead of time.
When this happens, the programmers often focus on solving the problem and forget about updating the technical design documents, so the technical design documents eventually become inaccurate and obsolete. Programmers rarely want to update technical design documents because the program may likely change again later anyway.
User manuals
User manuals are meant to teach people how to use the program. Ideally, a program should be so intuitive that users don't need a user manual. Because that rarely happens, most programs include a user manual that explains how to use every feature in a program.
Unfortunately, most user manuals are notoriously inaccurate, confusing, and incomplete:
If the programmers write the user manual, they tend to write instructions geared more toward other programmers.
If other people write the user manual, they often don't fully understand how the program actually works.
The problem with all forms of documentation stems from the dual nature of a software project:
Writing a program is completely different from writing documentation.
Writing the best documentation in the world is useless if the program never gets done or works incorrectly.
Programmers can use a couple of techniques for writing better documentation.
Agile documentation
Many programmers prefer using agile documentation methods. Just as agile programming means being able to adapt to changing conditions, agile documentation means updating the documentation just enough to be accurate but without wasting time trying to make it perfect.
Automation
Computer scientists have developed special documentation generators that can examine source code and create simple explanations for how different parts of a large program works.
By using such automated tools, keeping documentation updated is much faster and easier than forcing a reluctant programmer to write and update documentation manually. After documentation has been partially completed with an automated tool, the programmers can edit the documentation to keep it up to date.
Partially to avoid writing and printing manuals that few people bother to read anyway, programmers are writing help files instead. Help files essentially condense the user manual into short explanations that give users three options for finding help by
Browsing through a table of contents of logically organized topics
Searching an index for specific commands or topics organized alphabetically
Searching for specific terms or phrases
Help files can be read like a book, browsed through like a dictionary, or searched like a search engine that returns pages of related information. Like ordinary user manuals, help files often require the aid of programmers to explain and verify that the explanations in the help files are accurate and complete.
To make creating help files easier, many programmers use special help file creation programs, which can turn an ordinary user manual into a help file. By using such tools, programmers don't have to create user manuals and help files separately; they can just create a user manual and then turn that user manual into a help file. Ultimately, any form of documentation is meant to help explain what a program does and how it works. When writing documentation for your program, make it easy on yourself and write as little as possible while trying to be as complete as possible. It's not an easy task, but it's a necessary one.