Back to Blog

Self-explanatory code is good code, isn't it?

Lately I see more and more people who believe that code itself is the best possible documentation. As a result, some projects have zero-to-no comments, no diagrams, no documentation. For me this is a sad trend.

Here are 2 code samples (doing different things).

Java regexp.

    void String eliminateExtraSpace(String originalString) {
        return originalString.replaceAll("^ +| +$|( )+", "$1");

And test:

    assertEquals("Should eliminate extra spaces", "Some random string with spaces\nnew lines\n\t\ntabs\nand other characters.", eliminateExtraSpace(" Some random string with spaces \n new lines \n \t \n tabs \n and other characters."));

Lisp regexp.

    ;; Recognize the end of a sentence together with any white-space that follows.
    ;; In the output, tab and newline appear as themselves.
    ;; This regular expression contains four parts in sequence.
    "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
    ⇒ "[.?!][]\"')}]*\\($\\| $\\| \\| \\)[

In the first code sample it is harder to spot bugs. The code sample is self-explanatory and it is very clear how the code works now. But some questions remain unanswered. Should it remove leading spaces? Should it remove trailing spaces? Should it remove duplicate spaces? Unfortunately it is not clear how it should work (without knowledge of the initial requirements). Adding a few lines of comments could solve that problem, and allow to confirm that the test is actually valid (or invalid).

The second example is easier to understand and use, as it states the purpose and what it is doing internally. Questions such as: Will it recognize the end of the line? Will it recognize tab? are answered and the author’s intent is clear even to people who haven’t done regular expressions before.

The problem becomes obvious: self-explanatory code only tell how it is working. It rarely tells how it should work.

To have business value, code should do the right things, and should do them in the right way. The only way to ensure it is to write the same logic in different ways:

  • source code
  • documentation
  • tests

Tests are important to validate code. And the more people are working on the same codebase, the more important they become. But there are cases when testing fails.

For an example, I've seen code with 100% test coverage, that produce the wrong result. All tests pass, but consumers are not getting ordered products. Drawing a simple sequence diagram helped to identify the problem and fix it.

Self-explanatory code does not mean, that the documentation should be avoided. Comments and diagrams are important parts of the source code.

How to write good documentation? When to write comments? Here are some ideas that would help you to make the right decision:

  • Write the intent of the class/code.
    • If it is hard to specify the purpose of the class, maybe refactoring is required:class is a god object, or just a bunch of unrelated methods, or there are many highly coupled objects.
  • Write comments for each algorithm that has above average complexity.
    • E.g. algorithms with multiple nested loops.
  • Write comments when code is done differently from the rest of the code. E.g. workaround for 3rd party tool.
  • Draw a diagram with 15-50 items (n.b. an arrow with a name is also an item).
    • Less than 15: maybe it is already simple enough, that one sentence could explain it?
    • More than 50: would looks too complex, try to split it. Diagrams with many items are harder to read and update.
    • http://draw.io/ is free and good tool to create diagrams
  • Ask your colleagues to read the comments and the code. Confusion may show places where code or documentation could be improved.
  • Write an overview document of the whole code and mention the diagrams that would visualize important parts. Keep it clear and short.
  • When someone asks clarification about a piece of code, it is a sign that the code could be refactored, or at least explained with comments.

Big thanks to Frank Prößdorf, Ilkka Laukkanen and Akos Krivachy for proofreading. Cover image taken from the sas dummy blog.


  • Konstantin Petrukhnov
    Senior Consultant