Beginning Programming ALL-IN-ONE DESK REFERENCE FOR DUMMIES®

Chapter II.9. Documenting Your Program

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.

Adding Comments to Source Code

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 ...