Artur Södler Software-Qualität

Modularisation and Interfaces

"By modularity, the intelligibility of complex systems can be increased to humans." [Source: translated from german wikipedia]

That may seem right, but in fact it is the cart before the horse. Humans do think modular, this is why they understand systems easier which are structured the same way.

Let us make an excursion to the marketing: Werner Kröber-Riel describes in his standard work "Konsumentenverhalten" [consumer behaviour] on 176 pages most elaborately the way humans process informations. The essence is: Man can overviev no more than five or six "items" at the same time. If a program suite exists of more than 5-6 programs, or a main menu of more than 5-6 drop-downs, or a drop-down menu of more than 5-6 entries, or a dialog of more than 5-6 whatsoever..., then we find it considerably more difficult to maintain an overview.

As a consequence, program sources are best organized into 5-6 subdirectories of 5-6 source texts, each containig 5-6 classes having 5-6 methods, which in turn consist of up to 5-6 blocks with up to 5-6 statements. Take your liberties with this — but: the direction is right.

Here is some further advice:

•		Universal modules It is important to view beyond the horizon. Modules adjusted to their special purpose are rarely reusable. A date input ignoring non-leap years 1900 and 2100 cannot be used at the land registry office, for there are documents of 1900 and earlier times. Next, the function can support both the gregorian and the julian calendar, or even the roman. The buddhistic? Take it as a rule: As far as you think it will ever be necessary to your needs, and a bit more. Because the cost of a later amendment is always greater than doing it right in the first place.
•		Visualize interfaces. The financial accounting software downloads the account statement via HBCI in MT940 format. The account statement is processed to book entries. If you make available the intermediate file (the MT940 file), a smart user can quickly locate why umlauts and accents are tampered since December 2013: The savings bank has changed text coding from ISO-8859-1 to UTF-8 without adding a "byte order mark". And if you forgot to add support for a byte order mark, the user can quickly remedy until you have updated the software.
•		Benefit from development documentation. When you design a software, many documents are created. At the stage of software development, most of them rot along. As soon as amendments become necessary, only the program code is adjusted, rarely the development documentation. Include them into the revision control system, or deliberately into the source code. In some cases the documentation is even being generated from source codes using tools. Refine the development documentation to the end user documentation. No matter how — but use your own documentation!
•		Interfaces are slim. Plan them carefully. Which parameters are so self-evident and widespread, that they are better stored in thread-global data? Which parameters are only used in rare special cases? Which parameters can be simplified (e.g. type "choice" instead of "text")? For all pointers to dynamic data, please document who and when allocates and releases memory. Allocation and release of a resource should always be done on the same side of an interface.
•		Modules check parameters at their interface. Bad quality: Erroneous data make the application crash. Medium quality: Erroneous data produce erroneous results. Good quality: Erroneous data are detected at an early stage, this facilitates error diagnosis. Fanatic persons also check the results, good developers are content if they can prove that the results must be correct.
•		Intelligent protocols Another step forward: Logging all interface data. Thereby you can even afterwards analyze in which module which problem occurred. In order to control the flood of data, the most important data can be filtered during writing and reading the protocol. An example: A memory allocation and deallocation log, which automatically removes properly deallocated memory blocks from the protocol. The remainder is a list of unreleased memory blocks.
•		Context information If each and every module stores context information as a chain, you can use it for protocols and for error information. That works top-down, reversely to appending implication information to an error information.
•		Correct design mistakes thoroughly If you discover a module interface to be suboptimal, then act at an early stage and radically. Jettison legacy as soon as possible. Deliberately design methods to make sure all affected modules are adjusted. And if software is being delivered modularly: Design methods for a rollout of the changes. Because if software developers must fear consequences of adjustments, they no longer adjust the software.