Basic Project H ygiene Change control, coding style, and other - - PDF document

1 1

CIS 422 S98 / M Young 1/21/99 1

Basic Project H ygiene

Change control, coding style, and other

• bservations on avoiding messes

CIS 422 S98 / M Young 1/21/99 2

Change Control

• Typically three “builds” are current:

– Frozen: The “demo” version (shared) – W ork: The current integrated version (shared) – Play: Individual developer’s version

• Steps:

– Programmer checks out module to “play”, makes changes and tests against “work” modules of others – Programmer checks in module when it has been tested against the “work” version (this may require coordination) – O n a regular schedule, “W ork” version is tested and moved to “Frozen” version

2 2

CIS 422 S98 / M Young 1/21/99 3

Version M anagement

• Use RCS, SCCS, or similar for version

management and concurrency control (locking)

– Have a policy on holding locks: e.g., 24 hours or less

• O r use a “merging

”-based revision control system like C VS

– May need multiple RCS directories, or a protocol for indicating the components of “work” vs “frozen” versions

Flavio Sara Master RCS RCS Play Play Work Frozen

symbolic links

CIS 422 S98 / M Young 1/21/99 4

Distinguish “Derived” from “Source”

• All “ultimate source” should be under

version/revision control

• All “derived” objects should be produced

automatically (e.g., when you run “Make”)

– N ever edit derived objects

• Examples: O bject code (obvious?

), lex output

• W hen generating components, consider revision

procedure

– If post-generation changes are necessary, they should be saved and applied to revised version

3 3

CIS 422 S98 / M Young 1/21/99 5

Exploit H igh-Level Tools

• Use application generators, scripting languages,

libraries, etc. when possible

– Subject to constraints of portability, performance, etc.

• Consider generating parts of the application

– Example: An Awk script can generate a large C struct initializer for error messages or help from a more easily editable text file – Message table in program and user manual could come from the same ultimate source – Remember then: generated code is “derived”, not “source”

CIS 422 S98 / M Young 1/21/99 6

Effective Unit Test

• A little is better than none

– In a group project, the worst bugs are those from your teammates; yours are easier to find and fix – N ever “leave it for integration”: Give your teammates clean, tested modules.

• Test drivers:

– A fully automatic test driver should be part of delivered units, and should be re-run before turning over a change

• After ma

king a change, reg ression testing should be fully automatic (or it won’t be done)

4 4

CIS 422 S98 / M Young 1/21/99 7

Scaffolding

Build more than the application code

• Test drivers and cases
• Data structure viewers and validators

– For any complex data structure, build tools to view it

• n demand, and to perform validity checks
• Instrumentation

– Any performance-critical part of the program should be capable of measuring itself

• Stubs

– Build “substitute” parts for testing and debugging

CIS 422 S98 / M Young 1/21/99 8

Avoid Inappropriate Optimization

• Consider efficiency only when/where needed

– Efficiency is unimportant for many programs

• Have a concrete performance goal, and a ra

tionale for it.

• KISS: If the goal can be met by simple algorithms and data

structures, do not use complex alg

• rithms a

nd structures

– 80/20 rule: Efficiency is unimportant for most parts of a program

• Even if performance is a problem, it probably effects only a

small pa rt of the program. Identify them (by measuring), and put the effort where it matters.

– W ork at the highest possible level

• Start with overall design, then algorithms and data structures;

code-level optimizations s hould be used spa ringly, if at all.

5 5

CIS 422 S98 / M Young 1/21/99 9

Prefer Readable, Editable Files

• Avoid binary files and
• ther non-editable file

structures if possible

– If you must have them, provide readers & writers

• W hy:

– Debugging, experiments, prototypes, extens ions – Breaking build-order dependencies

Application Reader/ Writer File or database Readable text form

CIS 422 S98 / M Young 1/21/99 10

Compile-time Errors are Better than Run-time errors

• Principle: W henever possible, help the compiler

catch your errors

• Applications:

– Strong typing (the stronger, the better)

• Use explicit casts if necessary, rather than demoting types

– Access functions rather than public data in module interfaces

• W henever you can classify “correct” and “wrong” wa

ys to access the data

– Volatility markers: const (C++), “in” mode (Ada), “final” (J ava)

6 6

CIS 422 S98 / M Young 1/21/99 11

Suicide is N ot a Sin (for Programs)

• “Defensive programming”: check for errors and

violated assumptions

• Better to quick death with a suicide note, than a

lingering illness

– In C, C++: the “assert” macro or Gnu nana – In Ada, J ava, etc.: use exceptions

• throw exception as close as possible to sig

n of trouble

– Create “safe” versions of unsafe services

• e.g., malloc/free with extra checking (for C/C++)

CIS 422 S98 / M Young 1/21/99 12

Programs are for Reading

• Each line of code is written once, but read many

times

– Saving time in typing is a poor decision

• Code should be readable for the unfamiliar

programmer (e.g., maintenance programmer)

– O verall organization is more important than coding details; e.g., how can I separate the “front end” from “back end” files in the g++ compiler? – W ithin a file, most important is ability to scan for relevant parts

7 7

CIS 422 S98 / M Young 1/21/99 13

Architectural Overview

• “O rientation” documentation

– W hat are the organizing principles for this system – W hat are the major pieces and their interfaces – W here are the parts making up those major pieces

CIS 422 S98 / M Young 1/21/99 14

An architectural diagram of GCC

lexer parser front end L1 front end L2 . . . build emit Machine description Tree rewriter (not entirely accurate) language dependent machine dependent RTL tree

8 8

CIS 422 S98 / M Young 1/21/99 15

Orientation to GCC ...

• Front/back interface is (only)

– construction of register-transfer-language tree – invoking code generator after each procedure

• Code generation for each machine is controlled

by table (machdef.h)

• Should say where to look to answer questions:

– How would I build a native code J ava compiler? – How would I compile C to J ava byte codes?

CIS 422 S98 / M Young 1/21/99 16

Comments

• Header comments: W hat I should know before

reading the code

– Consider extracting and indexing them, as in J avaDoc

• Code comments: W hat I might need to

understand the code

– Avoid restating the obvious – Help the reader “recover the design”

• More is not always better

– But a ratio of 2-3 lines of comment for each line of code is often about right

9 9

CIS 422 S98 / M Young 1/21/99 17

H eader Comments

• Interface comments: State the contract

– W hat, not how

• If an interface comment sa

ys “first this procedure does foo, then it does bar”, then either the comment or the procedure is badly designed

• Design comments: Approach

– In the implementation, not in the interface – Provide an overall view

CIS 422 S98 / M Young 1/21/99 18

N amespace is Precious

• The “name space” of a system is the set of

available names (for programs, modules, files, variables, ...)

• In a large system, a “flat” namespace is quickly

exhausted

– “But there is already an object called Q ueue, so ...”

• Conserve namespace by ...

– Partitioning (e.g., use local names in preference to global names, create hierarchy (structs, packages)) – Using specific names with low likelihood of clash

10 10

CIS 422 S98 / M Young 1/21/99 19

Choosing N ames

• The wider the scope, the longer the name

– Global names (e.g., system constants, classes) should be very specific, even if the names are long and cumbersome – In very local scope, names may be shorter

• i and j are perfectly good index variable names, for small loops
• Distinctness matters more than length

– “Long_name_1” and “Long_name_2” are worse than “theta” and “gamma”

• Standards help

– like_this or LikeThis or Like_This; GLO BAL or Global_

CIS 422 S98 / M Young 1/21/99 20

Pretty-Printing

• Pretty-printed code can be read more quickly

– easier to “scan” for relevant parts

• Automatic pretty-printing exposes errors

– choose a style in which common errors are obvious – color, fonts etc. help too: e.g., distinguishing comment from executable code.

• Consistency helps

– Choose a team-wide standard, and stick to it