This section lists some aspects which should be taken into consideration when specifying and developing websites using Trex. It does not attempt to give a complete description of general specification and design activities which are independent of the use of Trex.

Reduce public exposure

A module can contain a large number of methods but only public methods can be called from outside the module. Seen from the outside the complexity of a module depends upon the number of public methods included in the module. A module which makes one or two methods public is usually easier to understand than a module which makes dozens of them available from the outside.

Modules where the ratio of public/protected methods is low are desirable in that a user of the module only needs to understand the functionality of the methods which are public from the module.

In addition, the writer or maintainer of the code in the module can change the internal structure of the module in any appropriate manner provided the external interface remains unchanged.

Reduce intermodule dependencies

A module which calls methods in many different modules will be more difficult to maintain than a module which only calls methods in a few different modules.

This is because each time we make a change to a module interface, we have to check all places in the code where this module is called. Reducing the interdependencies between modules simplifies the problem of maintaining these modules. We can simplify the system structure by reducing the number of different modules which are called from a given module.

Put commonly used code into libraries

Commonly used code should be placed into libraries. The libraries should contain packages. Great effort should be made in ensuring that those packages contain classes of the same type. Thus a package such as “Form” containing only classes for manipulating forms is a good choice, whereas a package, “Forms_Date” containing a combination of classes for manipulating forms and dates is a very bad choice.

Isolate “tricky” code into separate modules

Often a problem can be solved by using a mixture of clean and dirty code. Separate the clean and dirty code into separate modules.

Dirty code is code that does anything that you are not supposed to do (but have to do).

Concentrate on trying to maximize the amount of clean code and minimize the amount of dirty code. Isolate the dirty code and clearly comment or otherwise document all side effects and problems associated with this part of the code.

Don’t make assumptions

Don’t make assumptions about why a method has been called or about what the caller of a method wishes to do with the results.

For example, suppose we call a routine with certain arguments which may be invalid. The implementer of the routine should not make any assumptions about what the caller of the method wishes to happen when the arguments are invalid.

Abstract out common patterns of code or behaviour

Whenever you have the same pattern of code in two or more places in the code try to isolate this in a common method and call this method instead of having the code in two different places. Copied code requires much effort to maintain.

If you see similar patterns of code (i.e. almost identical) in two or more places in the code it is worth taking some time to see if one cannot change the problem slightly to make the different cases the same and then write a small amount of additional code to describe the differences between the two.

Avoid “copy” and “paste” programming!

Top-down

Write your modules using the top-down fashion, not bottom-up (starting with details). Top-down is a nice way of successively approaching details of the implementation, ending up with defining primitive methods. The code will be independent of representation since the representation is not known when the higher levels of code are designed.

Use the principle of “least astonishment”

The system should always respond in a manner which causes the “least astonishment” to the user - i.e. a user should be able to predict what will happen when they do something and not be astonished by the result.

This has to do with consistency, a consistent system where different modules do things in a similar manner will be much easier to understand than a system where each module does things in a different manner.

If you get astonished by what a method does, either your method solves the wrong problem or it has a wrong name.

Try to eliminate side effects

Write as much as possible of the code with side-effect free code. With a little care most code can be written in a side-effect free manner; this will make the system a lot easier to maintain, test and understand.

Share your modules with other developers

Trex is based on the open source philosophy of collaborative free software development and is licensed under the new BSD license. Trex is itself open source and builds on and supports other open source projects. The project thrives on developer contributions, in the form of both contributed modules and functionality to core.