COSC345 Software Engineering. Documentation

Transcription

1 COSC345 Software Engineering Documentation

2 Documentation Self-documenting code Comments Outline

3 Documentation And Comments McConnell Most developers like writing documentation If the standards aren t unreasonable It is a sign of pride (just like good layout) Documentation Outside the program Functional specification Product manuals First version written by the chief architect Revisions done by professional authors Can be as much as 2/3 of the project effort (Boehm, 1984) Inside the program We call these comments

4 Comments Source Code Documentation Detailed description of the code Most likely to be correct as they change with the code The best form is the code itself! Aim for total legibility, completely self-documenting code Use a straightforward approach to coding Choose meaningful variable names Use appropriate routine names Use named constants (no magic-numbers) Ensure a clear and consistent layout Reduce the use of break & continue: use a clean code flow Use simple data structures

5 What Does This Do? for i := 1 to Num do MeetsCriteria[ i ] := True; for i := 1 to Num / 2 do begin j := i + i; while ( j <= Num ) do begin MeetsCriteria[ j ] := False; j := j + i; end; end; for i := 1 to Num do if MeetsCriteria[ i ] then writeln( i, ' meets criteria ' ); Taken from McConnell

6 What Does This Do? for PrimeCandidate:= 1 to Num do IsPrime[ PrimeCandidate] := True; for Factor:= 1 to Num / 2 do begin FactorableNumber := Factor + Factor; while ( FactorableNumber <= Num ) do begin IsPrime[ FactorableNumber ] := False; FactorableNumber := FactorableNumber + Factor; end; end; for PrimeCandidate:= 1 to Num do if IsPrime[ PrimeCandidate] then writeln( PrimeCandidate, ' is Prime ' ); Taken from McConnell

7 McConnell s Checklist (adapted) Routines Does the name describe exactly what the routine does? Does it perform one well-defined task? Are all separate parts separated (into different routines)? Is the interface obvious and clear? Data Do type names document the declaration? Are variables well named? Are variables only used for the purpose they are named? Are loop variables given informative names (not: i,j,k,x)? Are enumerated types used instead of flags? Are constants used instead of magic values (and strings)? Are constants distinguished from types from variables?

8 McConnell s Checklist (adapted) Data organization Are extra variables used for clarity when needed? Are all references to a variable close to each other? Are data structures simple (do they reduce complexity)? Is complex data accessed through access routines (get and put)? Control Is the normal path of the code clear? Are related statements grouped together (and separated by spaces)? Are independent groups of statements in a separate routine? Does the normal case follow the if (and not the else)? Do control structures minimize complexity? Does each loop perform one and only one operation? Is nesting minimized (should you use a routine for that)? Are Boolean operations minimized (are they readable)?

9 McConnell s Checklist (adapted) Layout Does the program s layout show the structure? Design Is the code straightforward? Does it avoid cleverness? Are the implementation details hidden? Are domain structures used (rather then computer structures)?

10 Comments Are Bad! Comments make the code harder to read Worse: you have to read both Natural languages are imprecise Programming languages are precise Comments are long and prone to inconsistencies Programming statements are short and to the point How can a comment be clear if the code isn t clear? Out of date comments are dangerous Very few people keep comments up-to-date Highly commented parts of code have the highest error rate (Lind & Vairavan 1989) Don t comment tricky code, re-write it!

11 Comments Are Good! All the arguments against comments are true But those weren t good comments Comments should be used at a high level of abstraction High level languages for programming Higher level of abstraction for the comments Comments clarify the intent of the code Comments don t repeat or explain the code They should read like headings in a textbook One short sentence in natural language Disagreement between code and comments? Both are probably wrong! Comments make you think about the code If its hard to explain its probably wrong

12 What Does This Do? // write out the sums 1..n for all n from 1 to num crnt = 1; prev = 0; sum = 1; for (i = 1; i < num; i++) { System.out.println( sum ); sum = crnt + prev; prev = crnt; crnt = sum; } Taken From (adapted from McConnell): jeroen.a-eskwadraat.nl/projects/ vakken/prtki/website/collegelex1.pdf

13 Kinds of Comments Repeat of the code Pointless: read the code Explanation of the code Pointless: the code probably needs a re-write Marker in the code Used during development to mark what has to be done Remove when the coding session is over? Summary of the code Designed to help readers of the code Description of intent Explains the purpose of the code to a reader All comments (except summary & intent) are redundant Navigational markers are sometimes useful too

14 Comment Placement Individual lines Put on the end of the line of code What do these (real world) comments mean? long time /* no c */ mov ax, 723h /* R.I.P.L.V.B. */ Only comment when lines are complicated (better: break it up) Don t individual line comment a loop or block start / end Does it apply to the for or the contents of the for? Good for structure member declarations Good to mark a previous error (to stop someone fixing it) Blocks of code Indent with the block of code to maintain readability Explain what to expect (comment before, not after) Explain surprises Discuss why not how Avoid abbreviations

15 Comment Places Variables and types Comment units and allowable ranges Comment encodings (better: use an enum) Comment limits on input data Document each bit in a flag Document global variables (why must they be global) Relationships between variables Special cases Exhaustively comment a compiler work around How else can someone know why the code is peculiar? Exhaustively comment style violations Why was it necessary to break convention Don t comment bad code rewrite it (Kernighan and Plauger, 1978)

16 Routines '******************************************************************* ' Name: CopyString ' ' Purpose: This routine copies a string from the source ' string (source) to the target string (target). ' ' Algorithm: It gets the length of "source" and then copies each ' character, one at a time, into "target". It uses ' the loop index as an array index into both "source" ' and "target" and increments the loop/array index ' after each character is copied. ' ' Inputs: input The string to be copied ' ' Outputs: output The string to receive the copy of "input" ' ' Interface Assumptions: None ' ' Modification History: None ' ' Author: Dwight K. Coder ' Date Created: 10/1/04 ' Phone: (555) '*******************************************************************

17 Routines and Modules Keep comments with the code they describe Better: keep comments out of the routines Document the source of an algorithm So you can go and look it up (to fix any bugs) Mark routines with comments Helps break-up the code and helps with navigation Document modules Document the purpose (at the top) Remember: the routines are already documented

18 Recommendations Treat comments as code Keep comments indented with the blocks of code Make comments look like indented blocks of code /* Comment */ Comment as you go along You re unlikely to go back and do it later You need the comments while you are writing the code Don t write comments that are too long Never have a quota N lines of code per comment Because you ll write empty comments!

19 References S. McConnell, Code Complete, Chapter 19