Some Principles of Software Development

1. Some Principles of Software Development Chapter 2

2. Intellectual control • Maintaining control of the concept in one’s mind. • Complexity makes it difficult. • Use of natural language makes it difficult.

3. Complexity and control • There is a maximum amount of complexity the mind can handle before it loses the ability to grasp the situation. • Organization along several lines can help the mind build a “model” of the concept or problem that helps maintain control. • “Abstraction” can be a necessary by-product of this process.

4. Language betrays us • Natural language is very good at expressing concepts at a high level of abstraction (fuzziness). • Natural language serves the mind by “lumping” concepts together in “fuzzy” categories. • However, “fuzzy” categories do not serve the process of problem definition, so natural language makes things ambiguous…and that tendency works against our efforts to create a clear description of the problem!

5. Divide and conquer • Defining categories that provide clear and definite boundaries between problem elements can help us categorize the problem. • So, we can divide the problem into a set of smaller, loosely related problems which we can solve.

6. Independent parts • In order to divide the problem set into parts, we need to minimize the dependencies between the “smaller” problems. • Although the smaller problems are still really dependent on each other, the objective is to minimize dependency so they can be treated “as if” they were independent…with reasonable comfort.

7. 7 ± 2 rule Early studies by the phone companies showed that the human mind was able to grasp seven (plus or minus two) concepts at once. Hence, phone numbers became seven digits long. But even then, they were divided into additional groups of three and four (such as 682-3572), and area codes were later tacked on as an additional group of three.

8. 7 ± 2 rule (cont’d) The upshot of this principle is that any elements of a problem (or solution) should be organized in such a way that the mind can easily grasp it, implying that groups of five to nine elements are the best way to decompose (or compose) things.

9. Hierarchies Since the 7 ± 2 rule implies that large groups of things are a problem for intellectual control, we can create subgroups of the larger group to hold them. This notion of “subgroups” provides a conceptual hierarchy, which makes it easier for the mind to process. This notion can be modeled using a “tree” structure.

10. Know when to stop • Since we can divide groups into subgroups, and subgroups into sub-subgroups, and sub-subgroups into sub-sub-subgroups, it’s important to know when to stop. • If we add too much detail, more than is needed to grasp the problem or solution, we have needlessly taxed the mind, and created additional maintenance tasks that pose a risk later on in the process. It’s important to go just far enough and no farther!

11. Identify the “customers” • One of the best ways to gauge if we’ve gone far enough is to understand who will be using the work that we are doing, and what they will be using it for. • If the work product is targeted to make the “customer’s” job easier, then it’s easier to have an idea of what information is needed, and what is not. For instance, design documents need to be targeted towards giving implementers (and other designers) what they need to do their jobs.

12. Fuzzy into focus • During the process of software engineering, the engineer is taking a “fuzzy”, poorly defined product, and bringing it into focus. • Each step of the software engineering process should systematically add a level of detail to what is known, bringing a fuzzy notion into sharp focus over time.

13. Document it! • Information and decisions are important elements in the software engineering process. As information is obtained, it should be recorded! • Even when engineers discover that they don’t know something, they record it as something that is undecided, usually by annotating an entry as “TBD” (to be decided)! • Engineers can use “TBDs” to manage the unknown as equally well as the known.

14. Record it or it's lost • Since engineers are adding information and detail (“focus”), and since the 7 ± 2 rule shows us there’s a limit to what can be retained, engineers must document what is learned and decided!

15. Know what you've assumed • Many things that seem intuitive or obvious actually are not. As a result, it is very important to list the obvious assumptions along with other information. • Assumptions are important parts of any solution, but they should be ‘called out’.

16. Traceability • Information is often “derived”. For instance, the design is derived from the specifications. • If some of this “derived” information is called into question, it’s important to know what it was derived from. • Also, if a requirement changes, it’s important to know what was derived from that requirement so it can be checked! • Traceability “tags” information to show it’s “heritage”

17. A place for everything and everything in its place • Information should (when possible) be stored in a single, appropriate place. • Information can be stored in the proper place regardless of the phase: if important design details are discovered during the requirements phase it should be stored in an appropriate place in the design documents!

18. Documentation isn't a novel • The purpose of software engineering documentation is to communicate facts. • Documentation, regardless of how seemingly tedious, should communicate facts simply and directly.

19. Input/output is the essence of software • Software transforms a set of inputs into a set of outputs. • The definition of what outputs should be expected for a set of inputs is essentially the requirements. • The definition of the transform particulars (how it operates) is essentially the design.

20. Too much engineering is not a good thing • It is possible to “engineer a product to death”: time and quality are both essential! • Engineering something to perfection can require so much time that it becomes obsolete before it is completed. • Quality is essential! However, know what quality is! To use an idiom: “Don’t build a solid-gold hammer!”

21. If it ain't broke don't fix it • Defects should be fixed, but addition of a function that is not required can introduce complexity. • Complexity in turn, can introduce defects. • Strive for simplicity, or “elegance”.

22. The “creeping feature creature” • Often, features are “invented” by enthusiastic engineers. • More often, features are added at a late date by enthusiastic marketers. • New features should be added when needed, but accepting new features late can open a floodgate of new feature requests! • Each new feature may seem small, but engineers can end up being “nibbled to death by ducks.”

23. Expect to deal with change • New features are a fact of life. Competitors introduce new features during development cycles that can change cash customer’s expectations of the products under development. • Ignoring the cash customer’s expectations is not a good idea: no one buys the product, regardless of how well-engineered it is.

24. Plan for it • Since feature ‘creep’ is a fact of life, software engineering should be prepared to deal with late additions and changes. • The process used to build software should accommodate a reasonable level of change without “breaking.”

25. Fix it now • When problems are discovered, it is best to fix them ASAP (as soon as possible). • The reason? As more and more “derived” information is developed from the “incorrect” information, there becomes much more to fix!

26. Re-use past work • Past work has (hopefully) already been analyzed, documented, discussed and even debugged! • As a result, when building specifications, designs, tests or code, it is prudent to keep in mind how it might be used in the future.

27. Previous work well done is golden • Previous work is an asset, if it has been done well. • Re-usable work saves effort, therefore, it saves time. • Time is money.

28. Create software so that reuse is possible • If specifications, design, tests or code is to be reused, then it should have a tendency toward being “generic”. • It should also be well documented so that it is easy for other engineers to use it, since we aren’t the only ones that could benefit from re-using our engineering products!

29. Don't reinvent the wheel • If other engineers could be re-using our code and specifications, why shouldn’t we use theirs? • Don’t fall victim to the “Not invented here” syndrome: often other teams code or ideas are quite usable. Don’t be a code bigot! • “Don’t build what you can buy.”

30. Take responsibility • The quality of the product and the safety of the customer is ultimately the responsibility of every engineer on the project. • If you discover a problem, even if it is not in your assigned area, take responsibility for seeing that it gets corrected!