What Is Complete?

One way to circumvent this issue is to provide clear, explicit definitions for what “100% complete” really means. By declaring a core set of development tasks and assigning values to them, you provide a clean set of metrics that are used to clearly communicate a task’s status. This can be a huge benefit to everyone, as it allows managers to worry more about upcoming work instead of fretting over the true state of the project. It helps the company know that important items: documentation, peer review, performance testing, unit testing, and anything else essential have been completed.

Furthermore, it can help managers know where engineers get bottlenecked, which then allows them to provide better coaching of that person in that area, improving the overall quality of the team; which in turn improves the overall quality of the application.

Engineers now know exactly what is important to the company. Furthermore it removes from the engineer the responsibility to figure out what exactly the project manager needs to know, or wants to hear.

By declaring a core set of development tasks and assigning values to them, you provide a clean set of metrics that are used to clearly communicate a task’s status. This can be a huge benefit to everyone because it helps the company know that important items: documentation, peer review, performance testing, unit testing, all things essential, have been completed.

How Does It Work
To state clearly what complete is, managers need to determine what activities are an integral part of software engineering, and would need to be completed on deliverables before they are comfortable handing it over to QA. These might include unit testing, peer review, security review, and of course, the actually development of the item itself.

It is my belief that the essential items are (in order):

• Unit Tests Defined
• Development
• Refactoring
• Self-Review
• Peer Review
• Security Review
• Documentation

I’ll cover each one of these briefly.

Unit Tests Defined – Here I am using the definition for unit testing as used by extreme programming advocates:

“In computer programming, a unit test is a method of testing the correctness of a particular module of source code. The idea is to write test cases for every non-trivial function or method in the module so that each test case is separate from the others if possible.” (http://en.wikipedia.org/wiki/Unit_testing)

Unit testing should be done with an automated unit-testing framework, such as NUnit, mbUnit, etc. I am ambivalent about whether or not the tests should be written first, but I do believe that it’s imperative that they be designed first. It is only when they are designed that you have a handle on what the interface for what you are building will look like. The act of designing your unit tests also allows you to demonstrate that you understand the business process being represented by the code you are going to build. Do you know what conditions must be met for it to succeed, for it to fail? Do you know if any variations exist in the use cases for what you’re about to build? This knowledge will help you build a better solution.

Development – This is the meat of the actual engineering process. I shouldn’t have to go into detail about this, beyond that engineering should be done according to certain standards. These coding standards should state what is and what is not acceptable, what will garner the best performance in the deployment environment, etc.

Refactoring – After development, there will probably be areas that are identifiable as needing rework. This is where refactoring comes in. Refactoring is the task of taking the code and cleaning it up so that it makes sense logically, and will be easier to maintain.

In software engineering, the term refactoring is often used to describe modifying source code without changing its external behavior, and is sometimes informally referred to as "cleaning it up". Refactoring is often practiced as part of the software development cycle: developers alternate between adding new tests and functionality and refactoring the code to improve its internal consistency and clarity. Testing ensures that refactoring does not change the behavior of the code.

Refactoring is the part of code maintenance which doesn't fix bugs or add new functionality. Rather it is designed to improve the understandability of the code or change its structure and design, and remove dead code, to make it easier for human maintenance in the future. (http://en.wikipedia.org/wiki/Refactoring)

Software engineering is often a task done expansively, meaning that you spread the thoughts in your head around and try many things out before settling on the few ideas that work best. This is part of the creative process inherent in engineering. Refactoring is the where you return to tighten up your code and adding the polish to it that it needs before it is released.

Software engineering is often a task done expansively, meaning that you spread the thoughts in your head around and try many things out before settling on the few ideas that work best. This is part of the creative process inherent in engineering. Refactoring is the where you return to tighten up your code and adding the polish to it that it needs before it is released.

Self-Review

– Self-Review should be a time when you return to your code to run the unit tests and search for any glaring problems. All the unit tests should pass, and all of the code should meet the engineering standards set out by the company.

I also recommend using tools like FxCop to further the self-review. With a tool like FxCop, an organization can determine certain conditions that need to be fixed before it can move to the next level. Self-Review can be further complemented by tools like Resharper, a refactoring tool, that will flag variables and methods that are declared but never used, namespaces that are redundant, and gives you the ability to fix them immediately.

Peer Review – This should also be obvious. It really is a matter of a second pair of eyes doing the same activity that occurred in the Self-Review. As I touched on above, people have different perspectives on what done means, and that can cause problems. That can be turned into an advantage when doing peer-review, as different perspectives will give rise to discussions about best practices.

Security Review

– With this review, you have a specific set of security concerns that you are looking for. You are specifically seeking things that are security-related, as related by the architecture team. A security review is essential in any application that is client-facing.

The software being developed represents a part of the operational life of the company in some fashion. It will contain some or potentially all of the data that a company needs to operate. If you expose their core processes and data to danger through negligence, you’re not only being irresponsible, but you’re opening your own company and yourself to potential litigation. Don’t let that happen.

The software being developed represents a part of the operational life of the company in some fashion. It will contain some or potentially all of the data that a company needs to operate. If you expose their core processes and data to danger through negligence, you’re not only being irresponsible, but you’re opening your own company and yourself to potential litigation. Don’t let that happen.

To put it another way, a civil engineering company that did not verify that their bridge design would hold the anticipated load would be sued out of existence when the bridge collapsed.

Documentation – Once it is all said and done, the work you’ve done must be documented. Someone will be maintaining this code in the future, and you shouldn’t give them cause to curse your name. There should be a documentation standard as well, which makes clear what is expected. In a .Net environment, documentation should be done in such a way that tools like NDoc can consume it. Software engineering firms can lose huge amounts of money maintaining legacy systems. That can be money better spent on research and development, new and better equipment for the engineers, or best, as large bonuses for the wildly successful and competent engineering staff.

An Example

This is how I believe the breakdown should occur:
Unit Tests Defined – 10%
Development – 60%
Refactoring – 70%
Self-Review – 75%
Peer Review – 80%
Security Review – 90%
Documentation – 100%

So if you’re done with your unit tests, development, and refactoring on Task A and your manager asks you what the status of Task A is, you say that you’re 70% done. If you’re done with everything except the documentation, you’re 90% done.

Common Objections
Some will object that this system is overwrought or complicated. It is obviously possible to tailor this list to meet the requirements of each organization and project. Some projects are internal only and would not require anything more than unit testing, development, self-review, refactoring, and documentation. Client-facing applications should, however, strive for more structure instead of less.

Others will complain that it inserts too much rigidity into the engineering process. They’re right, in part. It does insert some rigidity into engineering; the right kind of rigidity. Software engineering is about process. We are in the business of converting a company’s business processes into code. In order to most accurately represent some other entity’s business processes, we must have our own processes laid out in a clear and explainable way. If our own process is one of chaos, we will make it much harder for us to succeed.

A similar complaint to the one about rigidity is that we must remain more agile to respond to the changing needs of the business. If it is agility that we seek, we must then turn to extreme programming, and begin to use its tools and methods. The important thing to remember about extreme programming, however, is that it already includes many of the very same items discussed in this document: unit tests, development (obviously), peer review (in the form of pair programming), refactoring, and documentation.

A final complaint is that this will take too much time; that it will extend the development time beyond what is reasonable. Yes, this adds some time to development, but it is time that is spent upfront, making a better product. Again, I point to other forms of engineering. It is better to take time to ensure the product is right and valid than to rush with something to market and hope that you avoid disaster. History is littered with the wreckage of bad engineering, the software you build, the project you work on, should not rest crumble apart in infamy.

Summary
In order to best accomplish the goals we have taken on, we must have a clear understanding of what is expected of us, managers must have a clear vision of what state the application is in, and executives must have confidence in the work being done as a whole. Please understand that this is not proposed so it can be used to micromanage engineers, or to bludgeon them with time tables. It is provided as a tool to minimize the anxiety in communication about deliverables. Clear communication and clear expectations frees all involved to do their job most effectively. It makes achieving success that much easier.