Minimum Understandable Documentation (MUD)

There is no dispute that documentation contributes to a developer’s understanding and helps a developer write reliable applications more quickly. However in startups or fast-pace environments, we need to prototype quickly and it is often that the code will be deprecated or not reused by another developer. In order to help developers with quickly understanding the implementation while do not spend much time on documenting own codes, I introduce a concept of Minimum Understandable Documentation – MUD (yeah, you can think of MVP) which guides developers to document codes quickly and efficiently.

Designed as the above goal, an MUD follows these guidelines:

It must be extendable to full documentation later
By following a subset of fully comprehensive documentation rules, we just need to add more information later for better documentation (for Javadoc tool, check the rules at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#principles).

It should be written in natural language
The advantages are it is fast to type and easy to understand. It should not contain tags or spacing which is more than 1 space (unless auto-generated).

Anything which is non-obvious must be documented
While the definition of “obvious” is subjective, it is safe to put yourself in a position of a dev who has an average brain and minimum knowledge of your implementation.

Codes are split into related blocks and documented
It is painful to look through non-separated tens of lines of codes, code separation helps developer divide-and-conquer the logics.

Unusual cases and validations must be documented
General rule is “do not trust your memory”, document anything that you think you should remember.
From the above guidelines, a typical MUD is formatted like below:

/**
* Returns an Image object that can then be painted on the screen
* (if have more time, briefly explain inputs)
* given an absolute url and a relative specifier
* (if have more time or implementation is non-trivial, 

* briefly explain the implementation)
* by downloading the link content and converting to an Image.
*/

public Image getImage(URL url, String name) {
    assertTrue(isValidUrl(url));

    // [no need to document here as it is obvious]
    Image result = null;

    // Get image binary data
    ....
    ....

    // Convert binary data to Image
    ....
    ....

    if ((...) || (...) && (...)) {
        // do something if some thing
        ....
        ....
    }
    else {
        // otherwise do some thing
        ....
        ....
    }

    return result;
}


No comments :