7. Development Guidelines

7.1 Design Principle Usage

This chapter lists of some of the key principles guiding the design of RapidContext. It is an attempt to explain some of the trade-offs, omissions and choices made for the platform.

Pattern	Anti-Pattern
Read this document as the RapidContext declaration of good taste, whatever that means. Consider the pattern examples as templates.	Do not read this as a set of absolute principles that can never be broken. The anti-pattern examples show that they already have been.

7.2 Less is More

The less code that is written, the less code needs to be maintained, corrected and refactored. By omitting difficult, poorly designed or rarely used features, time and focus can be shifted to more pressing needs.

Also, by not including poorly designed API:s in the product, it is possible to revisit the omitted feature at a later date. Hopefully with a better understanding, more realistic use cases and/or a better design proposal.

This principle is sometimes referred to as worse is better.

Pattern	Anti-Pattern
The built-in transaction support is limited to the most commonly used scenario. Code and work-arounds are required for other behaviours.	Built-in support for procedure call interceptors and more...

7.3 Declarative over Imperative

Using a declarative language over an imperative one has a number of advantages:

The source code becomes less verbose and easier to read
The data might be reused for other purposes
The data might become readable by non-developers

These advantages are especially valid for configuration parameters, data transformations or similar.

Pattern	Anti-Pattern
The user interface XML (`ui.xml`) format is less verbose and easier to read than JavaScript code (imperative) for the same thing.	Custom widgets are still not possible to create using XML, but require everything to be done in JavaScript code.

7.4 Simplicity over Documentation

An application that is simple or easy to use doesn't require much (if any) documentation. Using tooltips or small in-app help texts in the user interface, reduces the need for user guide or screenshot sequences.

Note that simplification of the user interface is not identical to reducing the number of feature or making development easier. On the contrary, simplicity often requires much hard work with auto-detection, generalization and various smart tricks in the interface. Generally, only the illusion of simplicity is desired.

Pattern	Anti-Pattern
The automatic detection of `java` location and available port number when launching the RapidContext server.	Creating new apps and plug-ins still can't be done without access to the manual or by copying from other apps or plug-ins.

7.5 Defaults over Configuration

Sensible default values should be used instead of forcing users to configure the application. When in doubt, use defaults suitable for the majority or for the least technically inclined.

This principle is also applicable when designing API:s, where common use cases should be made as simple as possible. This is sometimes referred to as optimizing for the common case.

Pattern	Anti-Pattern
The default `admin` user is created with a blank password when no other users are configured.	The app and plug-in configurations are mostly identical and should be possible to omit, using heuristics to set the defaults.

7.6 Implementation over Specification

Most concepts and features are better understood after creating a working implementation with real-world data, rather than by writing a specification. Working code is preferred over ideas.

This shouldn't be confused with the good practice of providing example data and interactions (use cases) before starting the implementation.

Pattern	Anti-Pattern
Implement new ideas or behaviors as plug-ins. If they prove useful, the core extensions may be suitable for inclusion in the platform.	No current example found

7.7 Dynamic over Strict Types

This issue has been debated at length elsewhere. Suffice to say here that dynamic types is a core feature in JavaScript (and many other productivity-improving languages), so it makes sense to try to take this into account when building Java code for RapidContext.

Pattern	Anti-Pattern
The generic `Dict` and `Array` classes add some generic duck-typing to Java. They also simplify serializing to JSON, HTML or `.properties` files.	The Java implementation of built-in procedures or procedure types still require a number of specific interfaces and classes that are rather strict.

7.8 Exploratory over Automated Testing

Automated testing is unsuitable for discovering usability or deployment issues, due to its controlled and automated environment. Also, the time required for writing scripted tests is often better spent performing ad hoc testing of apps and procedures. This is especially true for the type of fast-moving software that RapidContext encourages.

Pattern	Anti-Pattern
The Admin app makes ad-hoc testing (calls) of procedures easy and straight-forward.	No current example found