User Tools

Site Tools


about:describing_principles

This is an old revision of the document!


Describing Principles

All principles in this wiki are described using a certain description template. This makes the wiki a principle catalog.

Variants and Alternative Names

Each principle may have several alternative names. This may be because the same principle has been described several times independently from each other. A principle may also evolve over time, change its name, change its meaning, may be applied to other contexts, etc. So there may be several names referring basically to the same principle. This also means that the alternative names may roughly correspond to certain views on the principle. The views may differ slightly resulting in certain variations of the principle.

Alternative names are listed in this section and, if necessary, explained. Variations are also explained and, depending on the difference, may additionally be described on a separate wiki page.

Context

Principles apply in certain contexts. A context is a basic category for principles like OOD, web development, framework development, user interface design, etc. Is describes during which task the principle can be considered. A principle has at least one context but also may have several contexts.

Definition

The definition section states the principle is one or two sentences. This may be the original wording or a new one.

Description

As one or two sentences is never enough to explain a principle in detail, there is a separate section describing what the principle means and how it is applied.

Rationale

Principles normally are not hard rules but rather heuristics or rules of thumb. So there is no formal proof showing that the principle is correct in each and every situation. Nevertheless there needs to be a reason for the principle, meaning some rationale explaining why it holds. In order to apply the principle, the rationale is applied to the given design problem that is to be solved. If the rationale holds in this case, the principle may be applied.

Origin

This section describes where the principle comes from, where it has been prominently described, etc.

Evidence

Apart from the rationale there may be different evidence that the principle holds:

  • Proposed: If the principle is neither examined, not accepted it is proposed. This is the default.
  • Examined: A principle is marked examined if and only if it has been subject to scientific research showing evidence beyond constructed examples. So an examined principle may be considered state of the art. This state is called “examined” and not “proven” as the examination may have limitations and the principle may still be questioned.
  • Accepted: A principle is marked accepted if and only if it is widely used in practice. Acceptance is assumed if a publication (a book, etc.) well-known among practitioners describes it. So an accepted principle can be regarded state of the practice.
  • A principle may be both examined and accepted.
  • Questioned: Independent of whether a principle is proposed, examined, accepted or examined and accepted, a principle may also be questioned. This is the case when someone has expressed reasonable arguments against it. It doesn't matter who questioned the principle but there has to be some understandable reason. Furthermore the principle itself needs to be questioned. It is not sufficient that keeping the rule may inevitably also have some negative effects expressed by another principle. This is normal due to the nature of the principle definition used here. A principle is questioned if the positive effect it claims is questioned.

Relations to Other Principles

There are certain relationships among principles. This section lists and explains them so the consideration of one principle inevitably leads to other principles that can be considered.

Generalizations

A generalization of the principle is another principle that can be applied in a broader context or one that is less demanding. The principle is always a specialization of its generalizations. A principle may have several generalizations, for example when it is a consequence of two other principles.

Specializations

A specialization is a more concrete principle that either applies in a narrower context, or makes more prescriptions, or is some kind of corollary. The principle is always a generalization of its specializations.

Contrary Principles

Following the principle may have a negative impact on aspects addressed by other principles. These contrary principles are listed here and the consequence is explained. As with the principle itself the negative effect concerning the other principles are not guaranteed. There is just a high probability that there is this effect. Therefore these principles should also be considered if this one is applied. Typically but not necessarily a principle is contrary to its contrary principles.

Complementary Principles

A principle is always a reduction of the given design problem to a very specific aspect or effect. Other principles have to be considered too in order to have a full picture of the design problem. Sometimes when one principle is considered, another one is very likely to be relevant, too. Then this is a complementary principle.

Principle Collections

This section lists all principle collections (including principle languages) that include the principle.

Example

A self-contained example explains how the principle distinguished “good” and “bad” solutions with respect to the aspect the principle is about.

Description Status

As the wiki page evolves, it gets better and better. This section roughly states how complete it already is:

  • Stub: Typically a wiki page starts as a stub and is then enhanced over time. A stub only contains the most necessary information.
  • Incomplete: If the principle description is not yet complete but already contains significantly more than a stub, it is called incomplete. See wiki:incomplete for the precise requirements.
  • Complete: A wiki page with no obviously missing information is called complete. It may still be possible to enhance and improve it but there are no real gaps anymore. See wiki:complete for the precise requirements.

Further Reading

Apart from the original source which may be already mentioned inthe origin section there may be other articles, discussions and wikis discussing the principle. If they are worth looking into, they are listed here.

about/describing_principles.1354720482.txt.gz · Last modified: 2013-05-19 22:09 (external edit)