New Initiative in Programming - The Foundation for Open Project Documentation

Simplicity needs projection and good taste. L. Torvalds

It is a mistake to think that programmers wares are programs. Programmers have to produce trustworthy solutions and present it in the form of cogent arguments. Programs source code is just the accompanying material to which these arguments are to be applied to. E. Dijkstra

In engineering practice, “project” assumes the development of project documentation

Not long ago one of the authors watched how one notable programmer (participant of two ACM International Collegiate Programming Contest world finals) wasted 15 minutes trying to understand a short program (6 lines of code). He knew that the program presented an iterative solution of the classical "Hanoi towers" problem. Later we found another solution on the internet with a rather good description of the algorithm.

Open Source Code and Program Understandability

In fact open source software does not ensure program understandability. The leading analyst for BASF Corporation, professor N. Bezrukov of Fairleigh Dickinson University (NJ) and the author of the www.softpanorama.org web site, believes [1]: "The central question of practical programming is the question of source code understanding."

It is always good to have original source code, but the problem is that in most cases it is not enough. Understanding any non-trivial program requires additional documentation. This need grows exponentially with the quantity of the source code. Code analysis for checking initial project specifications and program understanding are two different branches of programming technology. For instance, try sometime to understand the structure of a compiler if you have no definition of the formal language which it compiles.

Anyone who has participated in large-scale software reengineering projects surely remembers the sense of helplessness when you see a heap of badly documented (but, perhaps very well written) source code. The availability of the source code does not help when there is no access to key developers and their ideas. If a program is written, for example, in the C programming language (a relatively low-level one) and its documentation leaves much to be desired, then all of the project design can disappear in the coding details. In such situations the value of high-level documentation including specifications, interface definitions and architecture description will increase the value of source code!

The lack of fit between source code and program understanding has resulted in the appearance of methods that unify source code and documentation. One of the most famous unifying attempts was undertaken by D. Knuth in his book "Literate Programming" [2]. Probably the most well-known pirated book in the history of computer science was "Commentary on Unix: With Source Code" [3], which contains high-level explanations of the source code of the Unix operating system even including a description of the algorithms used. This book has been copied and distributed illegally for more then twenty years since its publication in 1977!

If you have not participated in project from its early stages then its complexity and size is hidden from you in the source code. Understanding "ancient" code is probably one of the most difficult tasks for programmers if there is no documentation or contact with the initial developers.

And one more opinion: "Does any worthy freeware program, whose [source code] appearance does not arouse disgust, exist? Therefore there are rather few good freeware, in spite of its great amount" [4].

The possible result of this tendency was described by great Russian mathematician, L. S. Pontriagin: "Only well-done work brings pleasure! If it is done roughly, it causes aversion and bit by bit cultivates in the person immoral attitude to the labour" [5].

Why Are Programs Not Planned?

Here we can mention three examples of things that are commonly produced with no planning: children, works of art and, unfortunately, software.

So, working without source code is bad, but often working with source code is not good either. There is commonly a lack of documentation, which has to be made detailed, fine and accurate. Software source code should be included in the project documentation as one component.

It is also important to note that documentation does not depend on the amount of work. Even a single dress in a closet is sewn using patterns! Bridges, roads, skyscrapers are built according to documentation, but not software. However, the situation commonly observed in software development can be described by Weinberg’s Second law: "If builders built buildings the way programmers wrote programs, then the first woodpecker that came along would destroy civilization" [6].

Why are there so many documents associated with devices and hardware? That type of documentation is quickly understandable and designed for specialists with an average level of qualification. The documentation allows installation and modification of the device or hardware even after many years have lapsed. For programs, unfortunately, this type of documentation usually is absent.

One explanation for this state of affairs is as follows. First of all, devices and hardware are manufactured for use by outside consumers, so the lack of documentation would force the developer to spend the rest of the product life doing hardware support, but that is not usually the plan. In software development the situation is different. In most cases, the consumer of the source code (not of the final product, but only the code) is another developer within the same organization. The common opinion is that there are no good reasons to create good quality documentation inside the organization.

Secondly, devices and hardware are "hard" and software is "soft." This means that it is much easier to make changes to the software than to the hardware. In fact the majority of programmers pathologically neither read nor write documentation [7]. That does not, however, mean that there is no need for documenting software.

Experiments show that there are few young programmers who are able to write program documentation. Regardless of the fact that in their university studies they have passed examinations on many courses in mathematics, they did not obtain the ability to write logically. For example, the same object is often named “lamp”, “Lamp”, “bulb” or “Bulb” in the different parts of documentation. The confusion can be unlimited! Software development environments help to avoid such errors while programming, but when writing documentation there is no rescue.

Program development has also become similar to show business with its pursuit of profits. No one is interested in a project's future, especially the far future. The main concerns are "profitable" or "unprofitable" rather than "good" or "bad," although in most cases good technology is also the profitable one.

Unwillingness to write documentation may also be caused by the fact that the more closed (undocumented) the project is, the more indispensable the author is!

Such work styles, unfortunately, even extend to software development for especially crucial systems. Programs are written, but not planned! During planning, any techniques more complicated than CRC-card [8] or usage diagrams [9] are often considered to be too intricate and are not used. The programmer can always refuse to use any technology, substantiating it for his chief by saying that "he could not do it in time" [10].

As a result, even users do not think that erroneous program behavior is something extraordinary [11]. At present there exists a general opinion in society, that big houses should be planned and well-documented, but for software this is not needed. So why not ask the question: why in projects like a "Digital House" are its components planned and documented with different level of quality?

In conclusion of this section, we note that the present situation didn’t exist at the beginning of the software era, when programmers used big, ancient machines. At that time programs were planned and written very thoroughly, because an attempt at execution might be performed only once per day. Therefore it appears that technical progress has resulted in less responsible developers.

Advantages of Program Documentation

With good project documentation, software developers cannot hold their managers hostage. Even after a programmer's dismissal, his place can be filled by someone, often with a lower level of qualification and salary.

Is it possible to teach how to plan and implement programs in books? We think that it is, but currently only with separate books on project planning [11] and implementing [12]. Unfortunately, there are almost no books which cover both stages of software development. The absence of such literature could be filled by open projects, software with open documentation, which allows both the advantages and disadvantages of such systems. It is similar to new kinds of patterns [13]. Project documentation makes the refactoring [14] of the software easier.

Such documentation should contain, in particular, formal specifications of program logic, because "things, which have no formal specification, could not be verified and so could not be erroneous" [15]. "If there is no specification then there are no errors" [16].

Moreover, project documentation should contain "protocols" or sequences of computations which help to understand program functionality; programming theorists are forming the opinion that a set of protocols characterizing a program may be much better than the source code [17]. In addition, without project documentation, one of the main advantages of object-oriented programming - code reuse, may result in problems[18].

And the main point: Project documentation is necessary, because we know from the theory of algorithms (Rice’s theorem) that in general it is impossible to prove the correctness of any non-trivial computing algorithm having only the source code. "Non-trivial" means that there are simple programs which can be proven, but most cannot.

According to Turing, program understanding (as opposed to its execution) requires "astuteness and inventiveness." But source code analysis can not be automated and human analysis requires a huge amount of time. So it is impossible to draw any conclusions about program properties!

Mathematicians found a solution to a similar problem in antiquity by writing mathematical proofs with the help of human language (documenting proofs). This method differentiated the Greek mathematical school from the Egyptian school. In the Egyptian school, solutions of, for example, geometrical tasks were presented as a figure with an explanatory legend: "Look!" It is similar to understanding a program with only its source code.

To allow others to understand what a program does and how it does it, there is a need to give a detailed description for a person with an average level of qualification. This description has to cover the program's development and its static and dynamic properties. It actually represents project documentation and proves that the program computes the necessary functions (i.e. corresponds to the requirements specification).

Obviously we must assert that "project documentation" does not mean "operating documentation" (user’s manual, software development kit or something of this kind). It is also obvious that software project documentation is indispensable. For different projects it can be secret, partly open or open, but at least for the purposes of education, project documentation has to be open.

Requirements for Project Documentation

Documentation for critical software can be divided into two parts - basic, which should be created according to the standards and extra, developed for the needs of customer. Other commercial projects are usually documented at customer’s request.

The first type of commercial project must be well-documented, but it is not always done because there is not much experience in writing such documentation and people are not used to doing it, except in IBM and some other companies. A lack of time and budget are often the reasons for poorly documented projects. The customer usually requests only manuals and operating guides.

Non commercial software which is not educational is usually documented at the discretion of the developer. In most cases, the developer doesn’t see the need to document the project, except for writing comments in the source code and making understandable names for functions and variables.

So we face a sad situation, especially in the cases when non-commercial software is used together with commercial software and the customer has cut back on the development of documentation.

In the described approach, the code should be based on the documentation, not vice-versa. Meanwhile the documentation should describe not only the product itself, but also the creation process. It should be clear for the average computer user so that an average programmer after a few hours of work will be able to understand it. It is also desirable, that a user sit with you during documentation. Such a process, by analogy with extreme programming, can be named "extreme documentation."

Foundation for Open Project Documentation

One of the authors (Anatoly Shalyto) announced the creation of the "Foundation for Open Project Documentation" at the opening of the North-Eastern European semifinal competitions of the ACM International Collegiate Programming Contest (Saint-Petersburg, November 2002). In support of the foundation the http://is.ifmo.ru[^] web site was created.

At the Computer Technologies Department of Saint-Petersburg State University of Information Technologies, Mechanics and Optics a special pedagogical experiment began. Students were divided into nearly 40 groups with one or two persons in each group. Each group was to develop some project, using state-based programming technology (programming based on automata theory) [19]. The resulting systems with full project documentation are to be published on http://is.ifmo.ru[^] in the "Projects" section. Many of them are already available.

Here is a list of some of projects finished and in development:

1. concept of visualization of algorithms for teaching of discrete mathematics and programming;
2. realization of interactive scripts for educational animation using Macromedia Flash
3. environment for teaching and testing students for arbitrary subjects (with example for lessons of English language);
4. combined usage of compiler developing theory and state-based programming;
5. skeleton animation;
6. use of XML for describing the appearance of a video player (projects home site: http://www.crystalplayer.com);
7. control systems for different devices (diesel generator, elevator, turnstile, coded lock, cash dispenser, traffic lights, coffee-machine, phone and many others);
8. bank security system;
9. client-server architecture using state-based programming;
10. graphical user interfaces using state-based programming;
11. SMTP-protocol implementation;
12. classical parallel problems: "Synchronization of the Chain of Shooters" and "Task about Philosophers Dinner";
13. games: “Robocode” [20], “Terrarium”, “CodeRally”, “Sea Wars”, “Lines”, “Automatic Bomber”, “One-armed Bandit” and “Bank” (“Zavalinka”)).

Important note: Among hundreds of tanks for the “Robocode” game, only our tank has full project documentation [21]. The same can be said of our “Terrarium” [22] game.

It is logical to assume that if the world is moving toward open source projects, then it will also be time for wide acceptance of open project documentation. This will allow us to replace reading source code with reading project documents.

The End of the Tale

While developing one of our projects (the "Sea Wars" game), after eight correction cycles (and that is not a record), the project's author, a student in the Computer Technologies Department, began to smile like a Cheshire cat. We were satisfied by the quality project. Program has a good user interface, works well and was accurately documented.

But open project documentation has both advantages and disadvantages. One notable programmer (prize-winner of competitions of the ACM International Collegiate Programming Contest) looked through the source code and the project's author began to rework it again. This process (with breaks) continues more than half a year later and we hope that in this project everything will be perfect like in Chekhov’s stories: the face (user interface), the clothes (documentation), the soul (source code) and thoughts (programs work).

Why Should the Documentation be Open?

Open project documentation means, first, that the documentation should exist and, second, that it should be available for futher use and possibly for futher modification. The "Foundation for open project documentation" is free, anyone can support it, but it differs from the "Free Software Foundation" and the "Open Source Foundation" because the ideas and concepts of open project documentation can be used not only in free software, but in commercial software, secret software and other projects.

Conclusion

The great amount of work required to write good quality documentation does not allow us to think that the foundation will find acceptance in software development show business. The technology offered here is difficult, but currently it seems that only easy and agile methods [23] can be popular.

Nevertheless there are some fields of programming where it is impossible to succeed without hard work, so new people who need and like software with good project documentation will appear. For example, one of the students, after he saw the project documentation written according to our approach, said that it was more detailed than the documentation for a television set. He supposed that submarines were probably documented in same manner.

Even if the use of project documentation does not become popular, it is very significant from a pedagogical point of view. Developing well documented projects is useful for the participants. It is also important for those who just look through projects because of their cognitive and aesthetic value. You know that not all visitors of a museum are artists.

Let us finish with the quotation of one opinion about our approach: "There was a lack of Open Project Documentation. Almost all documentation for the commercial projects, unfortunately, serves as customer's property and they do not hurry to proclaim it. That is the cause of such small amount of real projects in the Internet. There are a lot of sites with source code, but next to nothing with the project solutions. I looked into the "Projects" section on your site (http://is.ifmo.ru[^]) and compared my solutions with those offered. It is a pity that I had no access to these works earlier. I will not spend so much time for projecting and developing!" [24]

Finally, we would like to point out that this article reflects the tendency of the last several years: software development seems to be maturing - transforming from an art through a science [25, 26] to an engineering craft [27, 28].

One of the pioneers of aircraft D. Douglas said once - "When the weight of the documentation becomes equal to the weight of the airplane, it is ready to fly", and A. Martin affirms, that the documentation for the famous Boeing 747 weighed more than the plane itself. The same idea concerns the development of software. Without the proper documentation the development process is out of control. Electronic formats of documentation have decreased the weight of the documentation, but it hasn't changed the fact of the matter.

This research is supported by Russian Fund for Fundamental Investigations (grant №02-07-90114, “Technology of Automata Programming Development”).

The materials of this paper will be reported on the Linux Summit 2004 (http://www.linuxsummit.org/summit2004_program.shtml).

References

1. Bezrukov N. Reiterated Look at “Council” and “Market” // BYTE/Russia. 2000. № 8.
2. Knuth D., Literate Programming. Stanford: Center for the Study of Language and Information, 1992.
3. Lions J., Commentary on UNIX: With Source Code. Annabooks, 1977.
4. Protasov P., From Below // Computerra. 2003. № 19.
5. Researcher of “Steering Wheel” // Informatics. 2003. № 11.
6. Bloch A., Murphy's Law // ECO. 1983. № 1-3.
7. Demin V., Problems of Working of Russian Developers on the West // PC Week/Russian Edition. 2001. № 32.
8. Badd T., Object-oriented Programming. SPb.: Piter, 1997.
9. Booch T., Rambo D., Jacobson A., UML. Users Manual. M.: DMK, 2000.
10. Fowler M., New Methods of Programming // http://www.spin.org.ua.
11. Booch G., Future Creation // Open Systems (Otkrytye sistemy). 2001. № 12.
12. Stroustrup B., The C++ Programming Language. M.: Binomial (Binom), Addison-Wesley, 2000.
13. Gamma E., Helm R., Johnson R., Vlissidis J., Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley, 1995.
14. Fowler M., Beck K., Brant J., Opdyke W., Roberts D., Refactoring: Improving the Design of Existing Code. Addison-Wesley, 1999.
15. Zaitsev S., Description and Implementation of Computer Nets Protocols. M.: Science (Nauka), 1989.
16. Allen E., Bug Patterns in Java. APress, 2002.
17. Ershov A., Mixed Computations // In the World of Science (V mire nauki). 1984. № 6.
18. Telles M.A., Telles M., Hsieh U., The Science of Debugging. The Coriolis Group, 2001.
19. Shalyto A., Tukkel N., Programming with explicit state separation // World of PC (Mir PK). 2001, vol. 8, 9. http://is.ifmo.ru (section “Articles”).
20. Shalyto A., Tukkel N., Tanks and Automata // BYTE/Russia. 2003. № 2. http://is.ifmo.ru (section “Articles”).
21. Ozerov A., Four Tankmen and the Computer // Magic of PC (Magia PK). 2002. № 11. http://is.ifmo.ru (section “About Us”).
22. Markov S., Shalyto A., Controlling System for Herbivorous Animal for “Terrarium” Game. http://is.ifmo.ru (section “Project”).
23. Cockburn A., Agile Software Development. NJ: Addison-Wesley, 2001.
24. Trofimov S., E-mail: info@caseclub.ru.
25. Knuth D., The Art of Computer Programming. MA: Addison-Wesley, 1998.
26. Kazakov M., Korneev G., Shalyto A., Using Finite Automata in Developing Logic of Algorithm Visualizers // Telecommunication and Informatization of Education. 2003, vol.6, http://is.ifmo.ru (section “Articles”)
27. Sommervill I., Software Engineering MA: Addison-Wesley, 2001.
28. Braude E.J., Software Engineering: An Object Oriented Perspective. NY: John Wiley&Sons, 2001.
29. Fox J., Software and its Development. Englewood Cliffs. Prentice-Hall, 1982.