Good communication and documentation are perhaps the most important aspects of the development process. We use several methods to communicate constructively and create documentation during the development and maintenance of software systems.
Mailing lists
Mailing lists have proven to be an indispensable means of communication between developers and users. Mailman’s mailing list manager is a simple, easy-to-manage Web tool for creating and maintaining mailing lists. Each project usually has a developer mailing list and a user mailing list. The developer mailing list contains detailed discussions of the project’s problems. The mailing list for users allows them to ask questions about the operation of the programs.
Users often help each other, so it’s common for developers to subscribe to user mailing lists as well, and even fix tips that seem bad to them. At the initial stages of the project, when the software product being created does not yet have users, this mailing list is not needed; when the project reaches a certain level of maturity, it makes sense for users to create a separate mailing list.
Mailing lists are also useful because they generate a searchable archive that serves as a source of documentation and contains the most up-to-date information about the use of the product being created. Thus, mailing lists are communication channels through which, as the system evolves, developers can quickly respond to changing conditions, such as a new version of the operating system or compiler.
- Wiki.
An excellent addition to mailing lists is a Web site that the developer community can co-edit. This makes it easy to document discussions on the mailing list. For example, consider a situation in which a release of a new version of a compiler results in a compilation error unless a special flag is specified during the build process. The first “lucky” person who encounters this problem will send its description to the mailing list for other users.
Someone from the developers will find a workaround, announce it in the mailing list and ask the user to check it out. As soon as he is convinced of the correctness of the proposed solution, someone will make an amendment to the wiki, which will then become part of the documentation. We use the free and open source MediaWiki toolkit.
- Doxygen.
Along with extreme programming, we have included the ideas of literary programming (literate programming) in the development process. Wayne Sual explains: “Normally, in literary programs, source code and documentation are combined in one file. Literary programming tools then process the file and produce either human-readable documentation or compilable source code”.
The Doxygen tool uses a simple comment markup language in C++ or C source code and generates extensive documentation for the code. Since the documentation is automatically generated, it can be updated every night to match the most recent version of the code in the change control system. Programmers usually don’t like to write documentation, but they love to write code. If documentation is developed in parallel with the coding process, it is much more likely to stay up-to-date and consistent with the code.
Error logging system
Another powerful tool is the error logging system. It allows developers and users to report bugs and other problems, and also serves as a place to store requests for the implementation of certain features, not letting them be forgotten. We chose the phpBugTracker web based system because it’s easy to install, has a clean user interface, and handles multiple projects with ease. When logged into the system, an issue is given a unique identifier and can be assigned a severity and priority.
The bug logging system administrator can give selected developers additional privileges that allow them to change the status of an issue and suggest solutions. You can attach files to the description of the problem, say, with test cases or fixes in the source code. The initiator of the problem report and the developer assigned responsibility for resolving the problem are notified by e-mail about the change in the status of the problem, which allows a dialogue between them to be established.
Having a good bug logging system isn’t everything. For this tool to remain useful, someone must manage it, and the development team must periodically meet and “sort” problems, that is, reprioritize them and reallocate them to the appropriate categories or performers. Sorting usually occurs before the release of a new version at a general group meeting (either in one place or via telephone or video conference). Without such attention, a list of mistakes can quickly turn into a list of things that will never get done.
Change control
All software projects, large and small, should use some form of change control. The change control system allows developers to track changes in programs over time. Many tools have been created for file versioning. Most of them are based on a central file repository. In it, files are usually stored in the form of a history of changes. When a developer changes a file, they must commit the change to the repository, making it available to other developers. If two people are editing a file at the same time, there can be a problem that has two main solutions:
- restrict developers access to files, allowing changes to be made only one at a time, with the permission of the central server;
- allow parallel editing of the same file and provide an automatic way to merge changes and identify possible inconsistencies.
Parallel editing is better for our development process. It allows some freedom in choosing a location, so that developers can edit the code while on the plane or at home. Among such tools for change control, the most popular is the CVS system, built on the basis of a client-server architecture. The project files are stored on the server, and the client can connect to it and retrieve a copy of the file, blocking changes from other clients. The client can request any version of the file in the system. CVS also allows you to tag and “fork” files.
A marker is a symbolic name for a group of files that represents a “snapshot” of a project at a given point in time. Branching allows you to develop in several directions simultaneously and independently. Changes made to one of the branches do not affect other branches. A special branch, which we call the “main tree” or trunk, is the main development branch from which files are checked out by default. The newer toolkit, Subversion, has several advantages over the CVS system and can be used instead. In particular, Subversion supports the HTTP/HTTPS protocol and allows you to move and rename folders, while branching and tagging are computationally less expensive.
When it’s time to release a new version of a product, one of the developers is assigned as the release manager. He asks developers to put all final revisions into a repository, which he then locks, leaving only write access to himself. The release manager then tests the system, and if the planned features are present in full, creates a separate release branch. The release manager then applies fixes only to that branch. CVS can be configured to prevent other developers from making changes to the branch, who can then return to the main tree and start developing the next version of the software product.