Documentation

1. Comprehending the present – Investing in the future. Documentation

2. Software Documentation– Happens throughout the software lifecycle. Software Design Requirements Analysis Implementation Systems Engineering Testing Deployment Evolution

3. Types of Documentation • For software to be used properly and maintained efficiently, documentation is needed. Usually, three separate sets of documentation are prepared for software: • User documentation, • System documentation • Technical documentation

4. User Documentation • User Guide • To run the software system properly, the users need documentation, traditionally called a user guide, that shows how to use the software step by step. User guides usually contains a tutorial section to guide the user through each feature of the software. • A good user guide can be a very powerful marketing tool: the importance of user documentation in marketing cannot be over-emphasized. User guides should be written for both the novice and the expert users, and a software system with good user documentation will definitely increase sales.

5. System Documentation • System documentation defines the software itself. It should be written so that the software can be maintained and modified by people other than the original developers. System documentation should exist for all four phases of system development.

6. Technical Documentation • Technical documentation describes the installation and the servicing of the software system. Installation documentation defines how the software should be installed on each computer, for example, servers and clients. Service documentation defines how the system should be maintained and updated if necessary.

7. Summary: Why Documentation ? • Provide for communication among team members • Act as an information repository to be used by maintenance engineers • Provide enough information to management to allow them to perform all program management related activities • Describe to users how to operate and administer the system

8. How to Document Code 1) At a minimum: each Source File should have a comment block at the top, with your name, the date, the program filename, and a short description in it. 2) Variables names should be self describing, exceptions being loop counters in for loops, etc. • intmyWeightInPounds; inttimeoutInMsec; 3) Function names should also be self describing • CheckForErrors() instead of ErrorCheck(), DumpDataToFile() instead of DataFile(). 4) Use consistent case. camelCaseIsFine 5) Indentation –e.g., you can use 3 spaces, not tabs. 6) No magic numbers – any number other than 0 or 1 should have a constant defined for it. Example: • const intsquareFeetInSquareYard = 9;

9. How to Document Code 7) Use spaces in all assignment statements, and always use brackets in control / repetition statements for ( int i = 0; i < someConstant; i++ ) { //do something } if ( a == b ) { //do something } This is sometimes referred to as “One True Brace”– and it should almost always be used. 8) Use meaningful comments to describe complex situations, avoid unless comments.

10. How to Document Code Summary: Class Comment Blocks • Place a header comment block at the top of each class/source file. • purpose of the class • who wrote it • where it fits in the general system • when the class was written and revised • why the method exists • how it uses its data structures and algorithms. • Expected input and possible output • Expected extensions or revisions

11. How to Document Code Summary: Class Comment Blocks • Place a header comment block at the top of each method/module. • why the method exists • who wrote it • when the method was written and revised • Where/when the method is called • where it fits in the general system • how it uses its data structures and algorithms. • Expected input and possible output • Expected extensions or revisions

12. How to Document Code Summary: Line comments • Line comments should be inserted into the source code to explain the objectives of a subset of the instructions comprising a module/method • to describe data declarations and blocks of code • where the purpose of a statement is not entirely obvious • Each major control structure (loop, selection) should be clarified through a line comment

13. Comments and Internal Documentation • Line comments are inserted into the source code to explain the objectives of a subset of the instructions comprising a module • to describe data declarations and blocks of code • where the purpose of a statement is not entirely obvious • Each major control structure (loop, selection) should be clarified through a line comment

14. Benefits of Documenting Code • Software Engineering is an extraordinarily expensive undertaking. • Because of this, it usually requires the code to stay around for a while - How long did Microsoft have to maintain/patch/(defend in court) Windows 95?

15. Benefits of Documenting Code • Turnover rate is also very high for Software Engineers – by some estimate as high as 30%. • So, even at a good company with a low turnover rate, say, 15%, with 100 software engineers, that’s 15 people that need to get up to speed on a project – and 15 people that took all their knowledge about what they coded with them.

16. Benefits of Documenting Code • Also note that for the maintenance phase of a project can run 50-80% of the total engineering effort. • So it’s very important for new programmers to be able to get up to speed in a relatively short amount of time.

17. Summary • Understand the problem before you begin building the solution. • Follow accepted standards for code/user interface design. • Write code that is readable. • Separate user interface and data management. • Design for the most efficient use of the program by the user. • Design code that can be re-used. • Keep the program simple • Localize input and output

18. Qu es ti ons? The End ______________________ Devon M. Simmonds Computer Science Department University of North Carolina Wilmington ____________________________________________ _________________