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