Documentation

Description

When you feel like writing a long and complex comment on aspects and the use of one element, try to refactor so that the comment becomes superfluous. Often documentations are even poorly written or completely unnecessary.

Context

Derived from: “Comments”
Explanations can sometimes be useful: When explaining why something is being implemented in a particular way. When explaining complex structures/processes (when all other methods for simplification have been tried and come up short). Note that this smell is called “Documentation” because it is compliant to the ArchiMate-Notation. Maybe it should be renamed in the future with a more accurate name, because it can be confused with a holistic documentation.

Cause

Comments are usually created with the best of intentions, when something is not intuitive or obvious. In such cases, explanations are like a deodorant masking the smell of fishy abstractions that could be improved.

Detection

Search for quite long (default length 256) documentation belonging to one complex element or comments explaining obvious things.

Solution

Refactor elements to make them self-explanatory.

Cypher query

MATCH p = (n)<br /> WHERE size(n.documentation) > $docLength <br /> RETURN p

Cypher count query

MATCH p = (n) WHERE size(n.documentation) > $docLength  RETURN COUNT (DISTINCT n)

Aliases

Comments

Tags

business, application, technology, within elements, The Dispensables, automatic detection

Query parameters

[
    {
        "name": "docLength",
        "type": "number",
        "default": 256,
        "description": "The character length of the documentation."
    }
]

Related smells

• Architecture by Implication (relates)

All smells