Principles Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Rule of Explicitness (RoE) ======

===== Variants and Alternative Names =====

  * Explicit Is Better Than Implicit (EIBTI)((Tim Peters: //[[http://www.python.org/dev/peps/pep-0020/|The Zen of Python]]//))

===== Context =====
/* fill in contexts here: */
  * [[contexts:Object-Oriented Design]]
  * [[contexts:API Design]]
  * [[contexts:Implementation]]

===== Principle Statement =====

Explicit is better than implicit.


===== Description =====

Solutions often differ in the level of explicitness. A feature can be implemented explicitly or it can be a side-effect of the implementation of another feature or a more general functionality. The same applies to module communication. A module can invoke another module directly or there can be various forms of indirections like events or observers.

RoE states that explicit solutions are better than implicit ones. Indirection, side-effects, configuration files, implicit conversions, etc. should be avoided.
===== Rationale =====

If something is realized explicitly, it is easier to understand. Implicit solutions require the developer to have a deeper understanding of the module as it is necessary to "read between the lines". Implicit solutions also tend to be more complex. So explicit solutions are assumed to be less error-prone and easier to maintain.

===== Strategies =====

  * Avoid indirection (but keep [[Low Coupling|LC]] in mind)
    * Avoid indirection though events/listeners/observers, etc. and use direct references instead.
    * Avoid indirecting middleware like messaging middleware in favor of direct communication. Explicit communication paths are easier to grasp and debug.
  * Avoid configurability (but keep [[Generalization Principle|GP]] in mind)
    * Avoid using configuration files for specifying behavior. Instead implement varying behavior explicitly.
    * Avoid highly configurable modules. Instead implement varying behavior explicitly.
  * Explicitly state which module to use
    * Avoid importing all classes of a given package/namespace and import the needed classes explicitly. In Java this means not to specify wildcard imports like ''import package.*'' and to avoid static imports. Similarly in Python this means not to use wildcard imports. In C++, do not import entire namespaces (e.g. do not use ''using namespace std;'').
    * Avoid ''with'' statements in Delphi and other languages having constructs that let you invoke methods without explicitly stating the associated object.
  * Explicitly name parameters
    * In Python and other languages that allow this use named parameters.
    * Avoid long parameter lists and use objects with explicit attribute assignments instead. (see [[Option-Operand Separation]])
    * Use parameter types that explicitly state what the input is. Rather use specific types for parameters like customers, articles, URLs, colors, money, etc. instead of using strings or integers for these values (see [[anti-patterns:primitive obsession]]).
  * Avoid implicit type conversions. 
    * In C# do not to specify implicit cast operations 
    * In C++ use the ''explicit'' keyword on single-parameter constructors
    * In PHP use the ''==='' operator instead of ''=='' where the type matters


===== Caveats =====

See section [[#contrary principles]].


===== Origin =====

  * First without being explicitly stated RoE has been a central design principle of the programming language Python((Guido van Rossum: //[[http://python-history.blogspot.de/2009/01/pythons-design-philosophy.html|Python's Design Philosophy]]//)). Python dates back to 1991.
  * Later this philosophy was stated as part of the "Zen of Python"((Tim Peters: //[[http://www.python.org/dev/peps/pep-0020/|The Zen of Python]]//))
  * The rule---although often not stated as such---is also known outside the python community((Martin Fowler: //[[http://martinfowler.com/ieeeSoftware/explicit.pdf|To Be Explicit]]//)). 
  * Extend and origin beyond that remains unclear.
  * The name "rule of explicitness" is newly introduced here.


===== Evidence =====
/* Comment out what is not applicable and explain the rest: */
/*
  * [[wiki:Proposed]]
  * [[wiki:Examined]]
*/

  * [[wiki:Accepted]]: Explained by Martin Fowler in ((Martin Fowler: //[[http://martinfowler.com/ieeeSoftware/explicit.pdf|To Be Explicit]]//)) and in virtually every Python book.

/*
  * [[wiki:Questioned]]
*/

===== Relations to Other Principles =====

==== Generalizations ====

==== Specializations ====

==== Contrary Principles ====

  * [[More Is More Complex]] (MIMC): Stating something explicitly requires more code.
  * [[Generalization Principle]] (GP): RoE often results in specific solutions. Generality often requires stating something implicitly.
  * [[Low Coupling]] (LC): Direct communication typically has the disadvantage of a higher coupling. Indirection reduces coupling but creates implicit/indirect communication paths. 
  * [[Don't Repeat Yourself]] (DRY): Following RoE sometimes leads to duplication.
==== Complementary Principles ====

  * [[Keep It Simple Stupid]] (KISS): Explicit solutions are often also simpler.
  * [[Murphy's Law]] (ML):The typical reason for RoE is to avoid unnecessarily complicated solutions and possibilities for defects. Don't lose sight of that goal.
  * [[Model Principle]] (MP): RoE states that [[anti-patterns:primitive obsession]] shall be avoided. Instead more specific types should be used in parameter lists. MP makes this even clearer: In object-orientation objects instead of plain integers or strings are used.
  * [[Law of Leaky Abstractions]] (LLA): Often abstractions create a level of implicitness. Abstraction leaks are one reason why explicit solutions can be considered preferable.

==== Principle Collections ====

{{page>collections:OOD Principle Language#Box}}


===== Examples =====


===== Description Status =====
/* Choose one of the following and comment out the rest: */
/*[[wiki:Stub]]*/
[[wiki:Incomplete]]
/*[[wiki:Complete]]*/


===== Further Reading =====

  * Martin Fowler: //[[http://martinfowler.com/ieeeSoftware/explicit.pdf|To Be Explicit]]//
  * Tim Peters: //[[http://www.python.org/dev/peps/pep-0020/|The Zen of Python]]//

===== Discussion =====

Discuss this wiki article and the principle on the corresponding [[talk:principles:Rule of Explicitness|talk page]].