This is the content of an email that I sent to the people that I worked with in the programming tools business unit. The email was sent in Jul 2003. By and large these were adopted by most of the developers of the business unit and continued to be practised over successive generations of developers. The practices were well ingrained and I doubt if later generation of developers were even aware that such a mail existed:-)
The practices were based on my reading of the following references:
1. Steve McConnell: "Rapid Development". Microsoft Press (WP Publishers, India)
2. Steve McConnell: "Code Complete". Microsoft Press. (Indian Publisher: WP Publishers)
3. John Robbins: "Debugging Applications". Microsoft Press (WP Publishers, India)
4. Steve Maguire: "Writing Solid Code". Microsoft Press (WP Publishers, India)
5. Masaki Imai: "Kaizen - The key to Japan's Competitive Success". McGraw-Hill International Editions
Documentation
See:
"Comment, Comment, Comment, And Comment", pgs77-78 of Ref3.
"Self-Documenting Code", Ch19 of Ref2.
"PDL for Pros", pgs54-57 of Ref2.
Please remember documentation is for YOUR customer. Who is your customer? Anyone who has to look at your code, or use it, is your customer; the developer who uses the services that your code provides, the reviewer, the tester, the maintainer, and last but not least - you. It is documentation that transcends space and time. To paraphrase (I think, Wordsworth), "Dust thou art to dust returnest was not spoken of documentation"
Comments need to convey what's in the developer's mind, not what a given statement is doing. Explain the "What & Why". Only then, explain the "How"
Two quotes from Ref3:
"I mean documenting your assumptions, your approach, and your reasons for choosing the approach you did."
"Donald Knuth once observed that you should be able to read a well-written program just as you would read a well-written book."
Develop the code in a three-stage step-wise refinement process. The artifact of each stage is to be reviewed.
First Function Headers. Function header should contain the algorithm. If it is from a text, then give the reference. The algorithm should just explain the broad idea of how the purpose of the function will be achieved. If the algorithm is getting unwieldy, it means more than one function is required. The algorithm has to be reviewed before proceeding.
Next PDL. The PDL refines the algorithm. Check if indeed it does that. The PDL must be in a style that will make them good comments.
Next Code. The final refinement. Check if algorithm, PDL and code are consistent.
Any changes to the code should be reflected back to the PDL and if necessary to the algorithm. The reasons for the changes should be given in the comments.
The DETAILED DESIGN, inclusive of functional specifications, will exist only in the source files, as file and function headers. NO WHERE ELSE.
Only the architecture design will exist as a separate document. It will be largely pictorial and show the interconnections and responsibilities of the modules. This document should be a part of the workspace.
NAMING CONVENTION: Follow the Hungarian Notation.
ASSERT
Read:
"Assert, Assert, Assert, And Assert", pgs48-58 of Ref3
"Assert Yourself", Ch2 of Ref4
And implement.
Globals
No globals. Any relaxation, to this rule, will only be made with the permission of the CEO.
Use Access routines. See pg231-233 of Ref2.
Test Each Function
Read:
"Step Through Your Code" Ch4 of Ref4
"Trust Yourself, But Verify (Unit testing)" in Ref3 pgs78-80.
Walk-thru your code by stepping thru every path.
Daily Build
Read:
"Daily Build and Smoke Test", ch 18 of Ref1
Get the bad news early!
Do this even on one-person projects.
A smoke test is just an indicator that the build has a reasonable chance of passing the full test and therefore, development can continue. If the full test throws up defects that necessitates the development to regress, then the smoke test is not adequate.
Creation of tests is a creative activity and will require the attention of skilled and experienced persons.
The further away we are from Daily Builds the more defect prone is our development process.
Daily Check-out and Check-in
Even on one-person projects use the CVS. Check-out the files at the start of the workday. Check them in at the finish of the workday.
Defects
All defects are to be recorded in the DTS (Defect Tracking System. This was implemented as a MySQL database).
Defect analysis does not finish with identifying the cause. Like Taiichi Ohno ask "Why?" five times (pg50 of Ref5). Analysis must identify reasons that caused the defect to be introduced; the reasons that caused it to be missed in unit tests. It must identify the remedial measures that need to be introduced in the development process.
Defects caught in reviews must also be recorded in the DTS and analyzed.
Checklists
The results of defect analysis must result in entries in checklists.
Each of the chapters in Ref2 ends with a checklist. Browse the book and choose your top 10. Use it when reviewing your own code or someone else's. Save a copy.
Keep records
Keep records, preferably as text emails, of all discussions and reviews. If it was not recorded, it did not happen.
Keep it Simple
"Finally, don't write code the way lawyers write contracts." - pg166 of Ref4
Use the QA C to keep a check on the complexity of your code. Document this metric in the function/file header.
No comments:
Post a Comment