Learning to Program

Documentation Beyond Comments

Comments are usually the best place for documenting how a single piece of code works. Comments aren’t as useful when you want to document how all the pieces of code work together (that is, how the program works). Flowcharts, diagrams, drawings, and narratives are much better suited for this type of documentation. Figure 5.12 from Chapter 5, “Data (Types), Data (Structures), Data(bases),” documents the structure of the library database, and Figure 7.2 from Chapter 7, “If, For, While, and When,” documents how prompt.js works. Diagrams such as these can be useful for describing big-picture ideas in your program. Comments are more useful for the nitty-gritty details.

Now it’s time to take our kittenbook documentation ...