1. High-Quality Routines Chapter 5-6

2. Review Class Quality Checklist 2

3. 3

4. 4

5. Outline 5 What is a Routine? Valid Reasons to Create a Routine Design at the Routine Level Good Routine Names How Long Can a Routine Be? How to Use Routine Parameters?

6. What Is a Routine? 6  An individual method or procedure invokcable for a single purpose  Function in C, macros in C/C++  Method in Java  What is a high/low-quality routine?

7. How Many Problems Can You Find? 7

8. Problems 8  Bad routine name – it tells you nothing  No documentation  Bad layout  InputRec is changed  if it is input, its value should not be modified (const), o.w. it should not be called inputRec  Read/write global variables  Read from corpExpense  Write to profit

9. Problems - cont 9  Non-single purpose  No defense against bad data – crntQtr =0?  Use of magic numbers - 100, 4.0, 12, 2, 3  Unused routine parameters: screenX, screenY  Two many parameters  Poorly ordered, undocumented parameters

10. Another Example 10 if ( ( (‘a’<=inputChar) && (inputChar <=‘z’)) || ( (‘A’<=inputChar) && (inputChar <=‘Z’))) { charType = CharacterType.Letter; } else if ( (inputChar==‘ ‘) ||(inputChar == ‘,’) || (inputChar==‘.‘) || (inputChar==‘!‘) || (inputChar==‘(‘) || (inputChar==‘)‘) || (inputChar==‘:‘) || (inputChar==‘;‘) || (inputChar==‘?‘) || (inputChar==‘-‘)) { charType = CharacterType.Punctuation; } else if ((‘0’<=inputChar) && (inputChar <=‘9’)) { charType = CharacterType.Digit; }

11. Valid Reasons to Create a Routine 11  Reduce complexity  Introduce an intermediate, understandable abstraction  Putting a section of code into a well-named routine is one of the best way to document its purpose  if (node<>null) then while (node.next<>null) do node=node.next leafName = node.name end while else leafName = “” end if  leafName = GetLeafName(node)

12. Valid Reasons to Create a Routine - cont 12  Avoid duplicate code  Creation of similar code in two routines implies an error in decomposition  Support subclassing  Need less new code to override a short, well-factored routine than a long, poorly factored routine  Reduce the chance of error in subclass if overrideable routines are kept simple  Hide sequences  Good to hide the order in which events happen to be processed  Independently get data from the user and from a file  Read the top of a stack and decrement StackTop variable  PopStack

13. Valid Reasons to Create a Routine - cont 13  Hide pointer operations  Improve portability  Simplify complicated boolean tests  Get the details of the test out of the way  A descriptive routine name summarizes the purpose of the test  Improve performance  Having code in one place will make it easier to profile to find inefficiencies  Optimize the code in one place instead of in several places

14. Operations That Seem Too Simple 14  Assume the calculation in a dozen places points = deviceUnits * (POINTS_PER_INCH/DeviceUnitsPerInch())  What does the expression mean?  Convert a measurement in device units to a measurement in points  Put the expression into a routine?

15. Function Version 15  Function DeviceUnitsToPoints(deviceUnits Integer): Integer DeviceUnitsToPoints = deviceUnits * (POINTS_PER_INCH/DeviceUnitsPerInch()) End Function  Function Call points = DeviceUnitsToPoints(deviceUnits)  More readable – even approaching self-doc  Any other benefit of the function?

16. 16

17. Design at Routine Level 17  Cohesion:  how much do two routines have to know about each other?  Criteria  size of the coupling  how many things do two routines share?  Intimacy  how closely coupled is the shared information?  Ex: Function A(p1, p2, p3) { Function B(p1); Function C(p2); Function D(p3); } # using local variables rather than global variables increases intimacy and visibility # hide data, but not manipulation of it.  Flexibility  how easily can you change the connection between routines?  you want to be able to change any routine without impacting other routines

18. Design at Routine Level 18  Functional cohesion – strongest and best  A routine performs one and only operation  Sin, GetCustomerName, EraseFile  Assume they do what their names say they do

19. Cohesion Less Than Ideal 19  Sequential cohesion – operations in routine  must be performed in a specific order  share data from step to step  don’t make up a complete function  Calculate Birthrate->age->retirement date  Communicational cohesion - operations in routine  make use of the same data, aren’t related in any other way  Print a summary and re-init the data passed to it  Temporal cohesion  Operations are combined into a routine because they are all done at the same time  Read config file->init scratch file->set up a memory manager and how an screen

20. Cohesion Unacceptable 20  Procedural cohesion  Operations are done in a specified order and the operation don’t need to be combined for any other reason.  A routine gets an employee name, then an address, and then a phone number – matching the order in which the user is asked for  Another routine gets the rest of the employee data - procedural cohesion  Make sure the calling routine has a single, complete job: getEmployee() vs GetFirstPart…()

21. Cohesion Unacceptable - cont 21  illogical cohesion  Several operations are stuffed into the same routine and one of the operations is selected by a control flag that is passed in  Control flow is the only thing that ties them together  Compute(), Edit(), Print();  Coincidental cohesion  The operations in a routine have no discernible relationship to each other  HandleStuff

22. Good Routine Names 22  Describe everything the routine does  Describe all the outputs and side effects  ComputeReportTotals - inadequate for ‘compute report totals and open an output file’  ComputeReportTotalsAndOpenOutputFile – too long and silly  Not to use less-descriptive names  To avoid side effects  Avoid meaningless, vague, or wishy-washy verbs  HandleCalculation, PerformService, DealWithOutput don’t tell you what the routines do

23. Good Routine Names - cont 23  Don’t differentiate names solely by number  OutputUser, OutputUser1, OutputUser2  Make names as long as necessary  Optimum average length for variables: 9-15  Routine names tend to be longer  For a function, use a description of the return value  printer.IsReady, pen.CurrentColor()  Use opposite precisely  Show/hide, open/close, source/target,…  FileOpen and _lclose  Establish conventions for common operations

24. Hong Long Can a Routine Be? 24  Theoretical best max length: one screen or one/two pages – approximately 5-100 lines  non-comment, non-blank  IBM once limited routines to 50 lines  Complex algorithm: 100-200 lines  Decades of evidence say that routines of such length are no more error-prone than short routines  Be careful if you want to write routines longer than about 200 lines

25. How to Use Routine Parameters 25  Put parameters in input-modify-output order  The sequence of operations - inputting data, changing it and sending back a result  Conflicts with the C-lib convention  If several routines use similar parameters, put them in a consistent order  Use all the parameters  Don’t use parameters as working variables int sample (int inputVal) { inputVal = inputVal * CurrentMultiplier(inputVal); … return inputVal; }

26. 26

27. How to Use Routine Parameters - cont 27  Document interface assumptions about paras  Whether input-only, modified, or output-only  Units of numeric parameters (inches, meters,…)  Meanings of status codes and error values if enumerated types are not used  Ranges of expected values  Specific values that should never happen  Limit the number of parameters to about 7

28. 28

29. 29