Guidelines
Jim Design Fawcett CSE687 Object Oriented Design Excerpts from and addendums to: "Enough Rope to Shoot Yourself in the Foot", Allen Holub, McGrawHill, 1995
Prime Directive
No surprises
Maximize Cohesion Minimize Coupling
A component, e.g., a module or class should act the way it looks like it should act. The interface should describe what it does in a way that any competent developer can understand. Things that are grouped together should be related in function and be focused on a single objective. When a component changes, everything it's coupled to may need to change. Try to couple only to interface, not implementation. Try to minimize "assumption" coupling and "need to know" coupling as well as data coupling.
Kiss Principle
Keep It Small and Simple
Don't solve problems that don't yet exist. Solve the specific problem, not the general case Keep the door open for extension through composition and inheritance Use polymorphism to encapsulate "need to know" in specific derived classes, allowing clients to be blissfully ignorant, knowing only the base class protocol. Design function code that it: Keep a module small enough that its structure chart fits on a single page
fits on a single page has cyclomatic complexity well below 10 but don't make it needlessly inflexible either
Separate Interface from Implementation
Use encapsulation to force clients to program to your interface, not your implementation. Hide any complex design details inside your implementation Make your interface simple and as small as is practical. Don't return nonconstant pointers in public interfaces: For classes, use private or protected keywords:
makes clients need to know your implementation
Use static keyword to hide global functions that are not intended for client use.
qualify all data as private or protected qualify as private or protected any methods that are complex or dangerous for client use
Decompose into Smaller Tasks
Break a complex operation into smaller simpler pieces.
Design is a decomposition process in the application domain. Implementation is a recomposition process in the solution domain.
if you can't say it well in English (Hindi, Mandarin, ...) you can't say it well it in C++ The act of writing out a description of what a program does, and what each component does, is a critical step in the thinking process. If you can't write it clearly then you probably haven't fully thought out either the problem or its solution. When you're done, you have a specification the only reasonable basis for testing.
Small is Beautiful
Large tasks are often best accomplished by a collection of small modular programs that use a common representation:
executing task can be very flexible use the right tool for this specific job use parts of the collection in ways the designer never thought of new tools are easily added as the tasks and goals evolve UNIX tool set control system computer aided design and analysis new uses often are created if the tools are flexible and easy to use
User Interface Should be Transparent
Don't let easy to learn translate into awkward to use. Interfaces shouldn't look like computers, they should look like solutions to a task. The fastest editor I ever used was the DEC RT11 TECO editor.
Measure productivity in the number of keystrokes it takes to complete a task.
It was a line editor, not based on a GUI It was brutally hard to learn because it used control keys for all commands Once you learned it, NOTHING interrupted your typing. You didn't have to stop and grab a mouse every third sentence. After a few months of use it became invisible. There was nothing conscious between you and the words flowing out on the screen.
Read Code
Read a lot of code.
Write a lot of code.
You learn by seeing how others write code. Look at as many samples of good code as you can. Look critically at your own code. Read several of the better trade journals, e.g., C++ report, C/C++ User's Journal, IEEE Computer Magazine, IEEE Software Magazine. When you're starting a big job, write small prototypes to try out your ideas and be prepared to throw them away or rebuild them before launching the final construction. Use an editor's red pencil on your code. Strike out unnecessary code, simplify, reword, repartition, until you're reasonably satisfied. Be prepared to throw the first one away.
Write for Maintenance
The maintenance programmer is you! Any software that is useful is written once, but read many times.
a lot less effort is expended over the lifetime of the program if the designer takes the time to document, design, and implement carefully as you build a module, the first functions built are reread many times as you build later functions that depend on them. careful unit test of a module will probably take more time than its initial construction.
You will spend far more time reading your code than writing it.
Others will read your code to understand when, where, and how to use it.
Performance is very Important, But...
Less important than correctness: Less important than robustness:
no point in generating errors very quickly no one will trust your code if it crashes often as soon as a program is put into service, if it's useful, users want more functionality. adding new features to unmaintainable code takes us back to the first two points we won't be in business very long if we're not as productive as our competitors. in a labor intensive business like software development, that means reuse
Less important than maintainability:
Less important than reusability:
Formatting and Documentation
Software should be selfdescribing:
Uncommented code has no value:
Unlike most other engineering disciplines, software has the ability, if well written, to capture, store, and disclose on demand, the technology used for its construction. if you use specialized algorithms or technology place citations to references you used so others can understand how your code works. uncommented code is unmaintainable manual and maintenance information should accompany every module every function should have a (brief) prologue perhaps only a single line and comments to describe any subtle code.
Documentation Style
Let code describe that which code describes best. Reduce clutter:
make comments as brief as possible don't put descriptive comments in class declarations, save them for member function definitions don't put inline functions inside class declarations. put them in the header file just after their class declaration and use the inline keyword
Diagrams
Use diagrams in requirements and design documents:
data flow diagrams to describe the basic abstractions and the information flows necessary to sustain them class diagrams to describe the static logical structure of your design event trace and activity diagrams to describe dynamic behavior structure charts to show calling relationships always provide one per module there if is significant function layering data structure diagrams show the organization of your data
Words are much less effective without diagrams, but ... A diagram may be worth a thousand words, but only if it is accompanied by a paragraph or two of discussion.
Comments
Don't comment the obvious. Do put comments where they are needed:
Once per module:
Briefly state purpose, operation, and public interface. Briefly list maintenance history Briefly state build process including file dependencies provide prologue: state name of file, brief phrase describing contents, state language, platform, application, and author state action discuss inputs and outputs only if type and format are not obvious put brief comments in code only if semantics are not obvious
Once per file:
Once per function:
White Space is Important
Show scope level with indentation. Set editor to replace tabs with spaces
you want tabs to be three or four spaces every printer on earth will make them eight spaces unless it is programmed to do otherwise
Use page breaks between functions that would otherwise be split across pages:
if your editor does not support page breaks, e.g., VC++, you can create one from the command line by copying a ^L from the key board to a file: copy con >ff //^L ^Z Then load the ff file into the editor, copy its contents, and paste it, inside a comment, wherever you need it.
Replace Tabs with Spaces
Names are Important
Well chosen names make code nearly self documenting.
names should be common words, describing what the file, class, function, argument, or variable does. use one character names only for indices declared, defined, and used locally use names just long enough to be descriptive. use a consistent style of separation, e.g.: severalWordName vs. several_word_name use typedefs, but use them sparingly
typedefs are quite useful, especially with templatebased identifiers. if typedefs are exported as part of the public interface, then describe them in the user documentation included in the module. avoid redefining standard types
Data Types are Important
Don't use global data except for constants that should be universally known throughout a module.
Don't return nonconstant pointers as part of a public interface
they give access to memory, not objects clients have to understand your design to use them properly
global names shared between components destroy their reusability nonconstant global data makes code maintenance very difficult
It is acceptable to return a reference to a welldesigned object:
the reference provides access to object only through its interface if you do, the object type referred to should be described in the documentation of your user interface both cause problems in recursive and multithreaded code
Minimize use of static data and try not to use global data at all.
Minimize Dependencies
Don't make unnecessary dependencies
only include header files that are needed in the file where included program to abstract interfaces wherever that makes sense never declare using namespace statements in header files
that minimizes compiletime dependencies and needtoknow
try very hard not to require preconditions for clients to use your code
that declares the using statement in any client's code that includes your header file
when you have to, make sure the conditions are documented as part of your user interface silent assumptions by one component about the behavior of another component cause a lot of grief during integration and maintenance of your code
Handling Errors
Test routines should not be interactive.
Every module should have a test stub. An error message should help the user fix the error. Don't display error messages if your code can recover from the error It is often very useful to provide error trace functions that are easily adapted to different environments:
use synchronization of output stream in multithreaded code use message boxes in GUI applications use streams which can be standard I/O or logging files
a noninteractive test routine can be exhaustive users providing inputs will not be nearly as complete
Always flush the output stream if more than one thre...