Building Routines. Quality Routines. Quality Routines. Quality Routines. Quality Routines. Routine. What makes a quality routine

Transcription

1 Building Routines Routine individual function or procedure invocable for a single purpose What makes a quality routine easier to see a low quality routine low quality routine coming up Procedure HandleStuff( Var InputRec: CORP_DATA, CrntQtr: integer, EmpRec: EMP_DATA, Var EstimRevenue: Real, ScreenX: integer, ScreenY: integer, Var NewColour: COLOUR_TYPE, Var PrevColour: COLOUR_TYPE, Var Status: STATUS_TYPE, ExpenseType: integer) begin for i:=1 to 100 do begin InputRec.revenue[i] :=0; InputRec.expense[i] :=CorpExpense[CrntQtr, 1]; end; UpdateCorpDatabase(EmpRec); EstimRevenue :=YTDRevenue*4.0/real(CrntQtr); NewColour :=PrevColour; Status :=Success; if ExpenseType = 1 then begin Profit := Revenue[i] - Expense.Type1[i]; end else if ExpenseeType = 2 then begin Profit := Revenue[i] - Expense.Type2[i]; end end; March 06 1 March 06 2 what s wrong with the previous routine bad name - HandleStuff() not documented bad layout modifies global variables (CorpExpense, Profit) doesn t have a single purpose initialises variables, writes to database, does calculations don t seem to be related uses magic numbers doesn t defend against bad data YTD*4/real(CrntQtr) make programs easier to read and understand helps save space and improve performance reduces repetition of code reasons to create quality code reduce complexity hide information so you don t have to think about it over and over avoid duplicate code why reinvent the wheel March 06 3 March 06 4 limit the effects of changes isolate area likely to change and reduce the effect hiding sequences program gets data from user and gets data from a file neither routine should depend on the other being performed first improving performance optimise in one place instead of several single optimisation benefits in many places making central points of control using one routine for reading from files etc March 06 5 if file data needs to be written to certain form, then only done in one place hiding data structures most of the program doesn t have to worry about structure manipulation provides level of abstraction to reduce complexity hiding pointer operations tend to be hard to read and error prone isolating allows improvement or replacement easily promote code reuse add modules to new projects March 06 6

2 planning for a family of programs basic model of software for everybody customisable parts in separate modules expect to change these for different customers making the code more readable well named routines make code easier to read and understand If (Node <> NULL) while (Node.next <>NULL) do Node = Node.next LeafName = Node.Name else LeafName = default LeafName = GetLeafName ( Node) March 06 7 improving portability using routines isolates nonportable capabilities nonstandard features, hardware dependencies identifies future work isolate complex operations scientific algorithms etc isolate use of non standard functions using nonstandard functions - double edged sword may not be available in other environments, platforms build gateway routines to the nonstandards to make them easier to replace March 06 8 Too simple for a routine? Is a 2 or 3 line routine overkill? Consider the following Points = DeviceUnits * (POINTS_PER_INCH / DeviceUnitsPerInch ()) not a complicated line eventually figure out the it converts measurement in device units to points clearer however to do the following create a function DeviceUnitsToPoints( DeviceUnits Integer ): Integer begin DeviceUnitsToPoints = DeviceUnits * (POINTS_PER_INCH / DeviceUnitsPerInch () ) end and then write the previous line as Points = DeviceUnitsToPoints( DeviceUnits ) more readable and self documenting also, may have to modify the function originally modify lines everywhere function call went may have to account for division by zero or some other error March 06 9 March how long is a routine? Theoretical maximum often described as one or two pages of code listing lines evidence in favour of short routines is thin arguments for longer routines routine size inversely correlated with errors as sized increased, errors per lines of code decreased Basili & Perricone study found that short routines were not correlated with lower cost or fault rate evidence suggested that lopnger routines were cheaper to develop per line of code empirical study of 450 routines found that the smaller (143 lines or less) had 23% more errors per line of code so what? If a routine needs to be 50 or 200 lines to make sense make it so current evidence suggests that routines up to 200 lines are no more error prone and cheaper to develop March March 06 12

3 > 200 lines - be careful line being a non comment, non blank line of source no study done has reported decreased cost or error rates with larger routines upper limit of understandability study of line program routines with fewer than 143 source lines were 2.4 times less expensive to fix March not my code does work, outside now! based on the idea of defensive driving never sure what the other drivers are going to do take responsibility for protecting yourself even when it is the other driver s fault defensive programming if a routine is passed bad data, it won t get hurt recognition that programs will have problems and modifications smart programmer develops accordingly March best form of defensive programming don t install the errors in the first place using iterative design, writing PDL before code, low level design inspections all used to prevent installing defects should be given priority over defensive programming Other Techniques Assertions function or macro that complains loudly if assumption is false March Assertions use them to document assumptions and to flush out unexpected conditions usually takes two arguments boolean expression that describes the assumption message to print if its not example instead of assert ( p!= NULL) if ( p!= NULL) { do something } March Assertions useful during development and maintenance assertion routine #ifdef DEBUG Void _Assert(char *, unsigned); void _Assert(char *strfile, unsigned uline); { fflush(null); fprintf(stderr, \nassertion failed: %s, line %u, strfile, uline); fflush(stderr); abort(); } #define ASSERT(f) if (f) {} else _Assert( FILE, LINE) #else #define ASSERT(f) #endif March Assertions use preprocessor macros for assertions easier to use during development and then take out for release avoid putting executable code in assertions asserting that the FileOpen worked call the FileOpen and assign the return value to a status variable then check the status variable March 06 18

4 Garbage in does not mean garbage out check values of all data input from external sources allowable ranges, strings lengths comment assumptions about input ranges check values of all routine input parameters Float Tan( float OppositeLength, float AdjacentLength) { Assert( AdjacentLength!=0, Adjacent Length is 0 return (OppositeLength/AdjacentLenght) } March decide how to handle bad parameters may want to return error code return neutral value substitute with next piece of valid data and continue return same answer as previous use closest legal value or default value lot of options architectural decision be consistent throughout the code you are writing March Exception Handling used to draw attention to unexpected cases should be handled in a way to make them obvious during development and recoverable after installation example is the default part of the case statement should give useful messages and be graceful Debugging Aids #ifdef DEBUG can write debug routines called to check various parts of the program and the data Firewalling to contain damage information hiding less you know about the internal workings of a routine less assumptions you make about it less chance that you are wrong loose coupling also helps when routines are not dependent on each other, an error in one is less likely to affect the other design interface boundaries anything inside the interface is safe and yours must decide where to put the boundaries March March Checking function return values always check the return value even if you don t have to guards against unexpected errors true for system functions as well How much defensive programming to leave in release code? During development, want errors to be as visible as possible, in release - want them unobstrusive March Leave code that checks for important errors what can afford to have undetected errors and what is too critical not to Remove code that results in hard crashes users don t appreciate loss of work no matter how helpful in finding a fault if your debugging code causes a system failure then remove it Leave in code that helps the system crash gracefully March 06 24

5 Make sure messages are user friendly too much defensive programming causes problems may cause the program to be fat and slow addition code may add additional complexity defensive code not immune to errors March make sure that the formal match the actual formal - in definition actual - used in actual routine calls common mistake to put the wrong types in calls put parameters in input-modify-output order only a suggestion be consistent by value or by reference if several routines use similar parameters, list all in the same order March use all the parameters otherwise remove what s not used two exceptions functions pointers in C or procedure variables in Pascal compiling parts of code conditionally certain parts may use certain parameters put status or error variables last convention to put these last in the list don t use routine parameters as working variables use local variables instead document interface assumptions about parameters if you assume that data passed to your function has certain characteristics, document this write the assumptions at the time of coding, not later input only, modified, output only units of numeric parameters March March meaning of status codes and error values range of expected values don t use specific values limit the number of parameters to about 7 depends on the complexity of the parameters and the data structures they are handling if you pass the same data to many different routines group the routines and use the data as module data consider input, output, modify naming conventions pass only the parts of structured variables that the routine needs may be better in some cases than passing the entire structure with 90% unused in the routine March March 06 30

6 Functions & Procedures The Purist Argument function should return only one value take only input parameters and return its only value through the function itself named for the return value Sin(), CustomerID() procedure take input, modify, output parameters common practice function operates as a procedure and returns a status value March example Functions & Procedures if (FormatString(input, formatting, output) == SUCCESS then... other option create a procedure and add a status variable as a parameter FormatOutput( input, formatting, output, STATUS) if (Status == SUCCESS) then... unique risk of functions return its value improperly March 06 32