Skip to main content
Engineering LibreTexts

17: Documentation and such

  • Page ID
  • Documentation

    Why have a chapter on documentation? Because documentation is needed for any program you write, however, it is also the most avoided essential. Why? Because of the oft used excuse that "I know what it does." But unfortunately you forget after!!!!

    Documentation is one of the most important parts of programming, it is also the toughest, and most poorly implemented in general. Here we will present some general rules for documenting any program (software project).

    • Documentation for all programming projects
      • A traditional documents on paper (or pdf or html or some universal way to read the document)
        • Manual
        • One page quick guide
        • Paper (or papers) explaining the raison d'etre for your program and the theory and solutions
      • Documentation within the program itself
    • All programming languages have some method of allowing the user to enter comments
      • Comments should be added at the beginning of the program
      • Comments should be throughout the program itself near important lines
      • Don't overdo comments as this distracts from the overall documentation
        • Example: we don't need a comment on a print statement that says it displays the string to the screen...we can figure this out without documentation
        • Example: you use a special numerical method that is not very common...yes please document this
      • Octave and its ilk note: the help in Octave give the front comments; lookfor give the first line
        • So if you don't have the front comments, help won't work...the professor will not be pleased...
        • Front comments can also be where you credit yourself (and your partners if applicable)
    • Good coding techniques acts as a defacto documentation of the code
      • Use tabs for statements in loops and conditionals, etc.
        • Note you have to do this in Python (so you are force to have good coding techniques)
        • A lot of editors (for coding) do this for you as long as you have a template for that language
      • Separate functions that are used multiple times into function, subroutines, or the like
    • exampleprogram_forceadd.png help_force_add_rev.png lookfor_function_rev.png
      This is the program that we will ask for help on the right. Observe the comments written in this program. NB: open the image in new tab or window if you are having trouble reading it. This is what help returns in Octave/MATLAB for the program on the left. You will see that the comments were important in order to get the help. This is true for all the functions in Octave/MATLAB, so do your comments! lookfor is a nice feature of Octave/MATLAB (in Scilab the feature is apropos - Octave is more aligned with MATLAB) that finds specific words in the first line of a program. As you can see here we wanted all programs that deal with "vectors." Of course this depends how well comments are written by the programmer, but it really helps when you forgot that function's name you remember that deals with "vectors" (in this example).
    • Documenting in a group project
      • Documenting in a group project requires some negotiation and sharing of responsibility
        • It is required of engineers to work in groups
        • It is required of instructors to grade you on group dynamics
      • Extreme Documentation
        • Characteristics
          • Document as project progresses (not after it is done)
          • Team ownership of project
          • Independent documentation from each programmer in the group (more eyes theory)
          • Compile documentation at the end in a traditional document and in the program itself

    Writing Good Programs

    To write good programs you should follow the procedures on documentation above, but what about the actual code? It is generally agreed that you should outline the procedure before you begin to actually code your program. There are two methods for outlining a program, flowcharts which has actually done before computer programming but adopt by programmers as well, and pseudocode where you code in a generic sense and to the specific syntax after you have gone over the pseudocode.

    • Flowcharts
      • Set of graphic "blocks" with connection arrows that represents the programming flow in a visual way
      • There has been work on using set theory to actually prove if a program is valid using flowcharts
        • Just proves you get a result and it follows you procedure as you believe would work
        • Can't really prove if the result is right or not as that takes an expert opinion in the field that the programming is being written for
      • There are programs that help with flowcharting or even run programs that you have flowcharted (raptor or flowgorithm)
      • There are modern additions that allow for parallel processing in flowcharting
      • Flowcharts have official ANSI symbols
      • While an old technique it is still useful
      • Flowchart symbols on a template that was used before personal computers.
        Flowchart symbols on a template that was used before personal computers.
    • Pseudocode
      • Programming in plain English (or any other language you wish) with a limited set of rules
      • Takes away the burden of strange (in the sense of our normal English sensibility) variable names, structures, methods, etc. imposed by different computer languages
      • Lets us write the way we "think"
      • Some pseudocodes have been developed with hardware and software interaction in mind
        • Software may actually be involved in changing voltage levels (think a controller) which is hardware in nature but controlled by software
        • Pseudocode is a generally enough idea that it can be used things not necessary computer programming related - just like flowcharts
      • While generally pseudocode is what you like to say in English it is generally agreed on that it should have words similar to programming languages
        • Might use read and print in pseudocode for a C++ program and those "pseudocode" words would be changed to cin and cout when you start to program
        • There is no official pseudocode

    Comparison of pseudocode and flowchart with very simple routine

    Pseudocode of a simple routine to decide whether to use atan or atan2. Note there is input and output and a conditional. Flowchart of a simple routine to decide whether to use atan or atan2. Note there is input and output and a conditional.
    Pseudocode of a simple routine to decide whether to use atan or atan2. Note there is input and output and a conditional. Flowchart of a simple routine to decide whether to use atan or atan2. Note there is input and output and a conditional.