Documentation for Developers Notes from Wilson, Software Design and Development pp152-154 And Fowler, Software Design and Development pp208-209

Documentation for Developers Two kinds of documentation for developers Process documentation Detailed records of the steps taken to define, build, check and modify the solution Data flow diagrams, flowcharts, interface design Details of any changes made to code since it was first written Product (or System) documentation Documentation for those who will use or administer the program Provides detailed description of the system Provides information for those who will maintain the system Provides information for those who may need to modify the system Includes, but not limited to – System Requirements System Description System Maintenance guide Trouble shooting guides Online Documentation

Process Documentation for Developers Can be one of two types: External documentation Not included within the program code. Examples are manuals, reports or updates on progress When this is for use by other developers should include algorithm used (in flowchart or pseudocode) metalanguage of any procedures or structures identify any special features the full program code listing test data and expected output Internal documentation Comments or ‘internal statements’ included in the program code to aid in developing or modifying the code Different programming languages have different syntax for comments Using meaningful names is another form of internal documentation (known as INTRINSIC documentation)

Internal Documentation Needs to be specific Should state Who wrote the program and when Program name Program version Statement about what the program is for, the logic in the program or that section of the code Should include description of any changes Should be set out clearly, including: Uses whitespace Uses indentation Uses clear, meaningful variable, subprogram and function names Be ordered, organised in a logical way