Index-> contents reference index search external Previous Next Home home-> links software journals packages publications resume pub_abstract white_paper ssh_key fedora_package bikelist rock_climb picture software Headings-> Prologue Quotes ---..Iterative Development ---..Sooner is Better ---..Clear Code ---..Refactoring ---..Verification ---..Optimization Unit Tests Test Driven Development Iterative and Incremental Development ---..Documentation ---..Specifications ---..Automated Testing ---..Distribution ---..Maintenance ---..Validation ---..Requirements

Software Engineering Procedures

Prologue
Often the people managing software projects have never written and maintained a large software system. This makes it hard for them to see the long term benefits of procedures that extend the time line for changes to the software. "The highest form of ignorance is when you reject something you don't know anything about.", Wayne Dyer .

Quotes
I have written some of the quotes below. The ones I have written are evolving / improving (and started in June of 2017). Please e-mail me if you know of a similar quote by someone else.

Iterative Development
1. "The minimum feature set is not the goal. ... You're selling the vision and delivering the minimum feature set to visionaries, not everyone." minimum feature set .
2. Start a project with a minimum feature set and then iterate. "You should use iterative development only on projects that you want to succeed.", UML Distilled .

Sooner is Better
1. "The sooner you find a defect, the cheaper it is to fix.", Extreme Programming Explained .
2. "Release early. Release often. And listen to your customers.", The Cathedral and the Bazaar .

Clear Code
1. "Any fool can write code that a computer can understand. Good programmers write code that humans can understand.", Refactoring: Improving the Design of Existing Code .
2. "If it's not clear that a condition is assumed true, add a comment about it in the source code. If the assumption might be false, include a check that halts the program, e.g., assert. If a user error can make the assumption false, include a message that helps users fix the problem.", Bradley Bell; see assertion (software development) .

Refactoring
1. "Each significant piece of functionality in a program should be implemented in just one place in the source code. Where similar functions are carried out by distinct pieces of code, it is generally beneficial to combine them into one by abstracting out the varying parts." Benjamin C. Pierce , abstraction principle .
2. "When you find you have to add a feature to a program, and the program's code is not structured in a convenient way to add the feature, first refactor the program to make it easy to add the feature, then add the feature.", Refactoring: Improving the Design of Existing Code .

Verification
1. "A program's documentation should include specifications so any expected results can be verified; i.e., reproduced by another program. It should also include an example for each feature that automatically checks for correctness; the simpler the better.", Bradley Bell; see software documentation .
2. "If you find a bug, create a simple counter example for use in a bug report and future verification.", Bradley Bell; see verification and validation .

Optimization
"premature optimization is the root of all evil. ... A good programmer will not be lulled into complacency by such reasoning, he will be wise to look carefully at the critical code; but only after that code has been identified." When to optimize .

Unit Tests
A system example and/or test is for the API of the entire system. A unit example and/or test is for the API of a piece of the system. Many programmers do not create an API for pieces of the system because this only helps developers (not users) of the system.

Test Driven Development
A simple development process can be diagrammed as follows:       |--------------|      |----------------|      |----------------|      | Automate new |      |  Code design   |      |  All automated |      |     test     | ---> |      and       | ---> |      tests     |      |  that fails  |      | implementation |      |    now pass    |      |--------------|      |----------------|      |----------------| see test driven development

Iterative and Incremental Development
The following process builds a foundation that makes development and use easier in the long run:       |--------------|      |----------------|      |----------------|      |              |      | Documentation  |      |  Code design   |      | Requirements | ---> |      and       | ---> |      and       |      |              |      | specification  |      | implementation |      |--------------|      |----------------|      |----------------|            /|\                                             |                      |                                             \|/              |--------------|      |----------------|      |----------------|      |              |      |  Distribution  |      |   Automated    |      |  Validation  | <--- |      and       | <--- | unit & system  |      |              |      |  maintenance   |      |  verification  |      |--------------|      |_---------------|      |----------------| see iterative and incremental development

Documentation
This is helpful if, people other than the developers will be using the program, or the program is large enough so that the developers can not remember it all. See software technical documentation . The technical documentation should be embedded in the software and kept up to date with it's changes. Trying to do this later will take a lot more time and not be as accurate.

Specifications
This is required for the program's results to be reproducible by another program; e.g., for the program to be verified. It also enables coding and implementation by people who do not completely understand the program. See design by contract . This should be part of the technical documentation and kept up to date.

Automated Testing
This is helpful when the program needs to be verified in multiple environments, or after multiple changes to the source code. See test automation . A new automated test, that is also an example, should be written when a new feature is added to the program. A new automated test should also be written to demonstrate each bug and later verify that the bug stays fixed. Writing these tests later will take a lot more time.

Distribution
Using a distribution tool that automates configuration for different systems is helpful if the program will run in multiple environments, or if the environment will have multiple updates and changes. For example, see cmake , and autoconf .

Maintenance
This is helpful if there are users that provide feed back and bug reports. See software maintenance .

Validation
This is a check, by users, that the software does what they intended. See software validation .

Requirements
This is improvements in what the program does. It is generated by balancing what the users want, with the difficulty and time required to get to the next validation. It is best to represent requirements as changes to the documentation so users understand the changes and developers can make and verify the changes. See requirements analysis .
Input File: software.omh