The Quixotic Engineer

I’ve been following a very interesting thread on the skrud.net forums recently about the role of formal documentation in the software process. In it, Dr. Constantinos Constantinides interjected with some sound arguments in favor of formal documentation. I thought he presented a very persuasive defense of an aspect of software design that is often maligned by undergraduate students. Because the thread in question requires forum registration to read, I sought his permission to reproduce the arguments here

The topic of discussion was SOEN341, Concordia’s “Software Process” class. Many past and present Concordia students were grumbling about what they felt was excessive formality and an overemphasis on arbitrary documentation completeness in the class. Dr. Constantinides’ argument was as follows:

In Software Engineering, I am not much interested in those things which you either can build on your own or you build only for yourself. I am very interested in those things that you alone cannot build and in those things that you together with a team of engineers build for others. In doing that, you must prove to me (your boss, line-manager, stakeholder, etc.) that what you are about to build is what you are expected to build (validation), and what you have built is what you were expected to build (verification). Asking me to “just trust” your code because “you know what you are doing” (maybe because you had a high GPA in some college, or you’ve been programming in this language for many years, etc.) is not enough for me. I cannot trust my medical / financial / … data on how sexy your CV looks. I want proof of concept for a solution to my problem. Architects and civil engineers refer to this as “blueprints”; Electrical engineers refer to this as “circuit diagrams”, etc. The proof of concept can done by paper and pencil, chalk on a blackboard, drawing software, etc.

Later in the discussion he elaborated on this position:

Let us talk about development as the production of a number of artifacts, at various levels of abstraction.

In my opinion EVERY artifact produced during development is important: You have artifacts produced in a natural language (e.g. English), others produced in a modeling language (e.g. UML) and others produced in a formal system (e.g. C++). You must be fluent with all different languages because you use each one for a different purpose. Yes, we can argue that implementation is vital because code is absolutely necessary for a system to run. However, in the absence of a requirements / analysis / architecture / design model, your level of confidence on the correctness of the system is rather low (and the maintainability of your system is very low).

Someone told me: “Go to the code.” Yes, I can do that. I should be able to do that. The code describes your rationale at a very low level and it’s not very helpful for a number of reasons including a) I need to stop you from doing something wrong before you start coding and b) a formal system is rather cryptic when it’s the only means of communication. Again, let me reiterate that I am interested in VERY large scale systems, not something which is a couple of thousand lines.

To maintain a high level of confidence, you must build strong confidence during requirements analysis (validation) and maintain it throughout the development life cycle. Because as your project manager I am the one who is responsible for it (see: lose the contract, being sued, etc.), then if your use case model is not validated I will not allow you to proceed to analysis. If your analysis model is not validated I will not allow you to proceed with architecture-design and if your architecture-design is not validated I will not allow you to map it to code. If your code is not correct (if tests fail etc.) or consistent, I will not allow you to consider the verification of requirements successful (for example, assume iterative process).

There is no such a thing as “documentation and source code.” I would love to eliminate the word “documentation” from our vocabulary. Let us talk about artifacts and models. With the exception of the magnetic 1s and 0s, everything else (installation scripts, user’s manual with screen shots, test suite, source code, supporting libraries, architectural-design model, analysis model, use case model – requirements) can be regarded as “documentation.” However, the problem is that many software engineering textbooks (and many instructors in many schools) place emphasis EITHER on requirements / analysis / architecture / design XOR (that’s an exclusive OR) on implementation. I think this creates confusion (and frustration) among students. Especially in the first case (emphasis on early stages only), it is very frustrating to focus on formatting (and dissemination) of reports and other issues as if a model will be mapped to implementation by magic or as if it’s not our job to map it. Give me the design mode in pencil and paper, as long as it is correct. Show me that you can faithfully map it to implementation.

Because of the above and with all tradeoffs considered, then my view is that ALL artifacts are equal. In fact, there are artifacts produced even after deployment (e.g. execution traces) which are valuable for post-deployment tasks (maintenance and evolution).

[…]

One last comment. There is a misconception (among us) that Software Engineering is that bureaucratic activity you do AFTER you build something to provide supporting documentation and explain what you did so that you can satisfy your instructor/ line manager/ boss, etc.. This is wrong. The adoption of UML as a common vocabulary helps us produce small documents and the advancement of modern (iterative) process methods helps us do the whole thing with confidence. Software Engineering is not about avoiding programming. In fact you cannot be a good software engineer if you are not a very good programmer.

Thanks again to Dr. Constantinides for allowing me to quote him here.