Software Engineering Routine design

High quality routines Routine: individual method or procedure invocable for a single purpose

High quality routines Low quality routine: (Code Complete, 2 nd ed., chapter 7 – page 162) void HandleStuff( CORP_DATA & inputRec, int crntQtr, EPM_DATA empRec, double & estimRevenue, double ytdRevenue, int screenX, int screenY, COLOR_TYPE & newColor, COLOR_TYPE & prevColor, StatusType & status, int expenseType ) { int i; for ( i = 0; i < 100; i++ ) { inputRec.revenue[i] = 0; inputRec.expense[i] = corpExpense[ crntQtr ][ i ]; } updateCorpDatabase( empRec ); estimRevenue = ytdRevenue * 4.0 / (double) crntQtr; newColor = prevColor; status = SUCCESS; if ( expenseType == 1 ) { for ( i = 0; i < 12; i++ ) profit[i] = revenue[i] – expense.type1[i]; } else if ( expenseType == 2 ) { profit[i] = revenue[i] – expense.type2[i]; } else if ( expenseType == 3 ) profit[i] = revenue[i] – expense.type3[i]; }

High quality routines Low quality routine:  Bad name: HandleStuff() does not inform what the routine does  Routine is not documented  Routine has a bad layout (compare e.g. the styles where expenseType == 2 and expenseType == 3)  Routine reads and writes global variables (corpExpense and profit) – bad way to communicate with other routines

High quality routines Low quality routine:  Routine´s input variable, inputRec, is changed. An input variable should not be modified, and a modifiable variable should not be named inputRec  Routine does not have a single, clearly identifiable purpose

High quality routines Low quality routine:  Routine is not protected against bad data (if crntQtd is zero, ytdRevenue * 4.0 / (double) crntQtr causes an error)  Routine uses “magic numbers”: 100, 4.0, 12, 2, 3  Some parameters are not used: screenX, screenY

High quality routines Low quality routine:  Routine has too many parameters (we should avoid more than a maximum 7 parameters)  Parameters are badly named  Parameters layout is poor  Parameters are poorly ordered  Parameters are not documented

High quality routines Valid reasons to create a routine:  Reduce complexity  Introduce an intermediate, understandable abstraction  Avoid duplicate code  Hide sequences  Hide pointer operations  Improve portability

High quality routines Valid reasons to create a routine:  Simplify complicated boolean tests  Improve performance (actually, give room to performance tuning) ... plus the previously seen good reasons to create a class

High quality routines Do not be ashamed to create very small and very simple routines. The abstraction may well be worth it.

Routine design Major keyword: COHESION A routine should do ONE thing well and not do anything else e.g., Cosine() is probably better than CosineAndTan()

Naming routines Describe everything the routine does Avoid meaningless, vague verbs Do not differentiate routine names solely by number Make names of routines as long as necessary Typically, good variable names are 9 to 15 characters long. Typically, routine names are longer

Naming routines To name a function, use a description of the return value To name a procedure, use a strong verb and an object Use opposites precisely (e.g. add/remove, begin/end, create/destroy) Establish conventions for common operations (e.g. avoid student.id.Get() and lecturer.GetId() in the same system)

Routine parameters Put parameters in a consistent order grouped by input, modify and output, e.g. input-modify-output Consider creading IN and OUT keywords – e.g. in C++: # define IN # define OUT In C++, consider using const for IN parameters

Routine parameters If several routines use similar parameters, put similar parameters in a consistent order Use all the parameters Put status or error variables last Do not use routine parameters as local variables Use local variables instead

Routine parameters Document interface assumptions about parameters Avoid too many parameters – seven is a good maximum Consider a naming convention to identify input, modify and output variables