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.
====== Communication ======

Communication is a central aspect in software development. A team can only perform well if the communication between the team members is good. One difficult communication task is to explain reasons for certain decisions. 

{{ :about:trustme_bad.png?nolink&600 |}}

There are convincing reasons, less convincing ones, misleading ones, ways of persuading people, etc. The following arguments are bad ones:

  * "Trust me" -- this is no reason
  * "My experience tells me" -- this does not explain anything
  * "Using your reasoning you can excuse bad code" -- every single aspect taken to the extreme leads to bad decisions. Just because things can be made //too// simple, does not mean simplicity is a bad thing, etc.
  * ...

Principles are proven reasons for judging design solutions. Reasons which do not persuade but point to important aspects of consideration.

{{ :about:trustme_good.png?nolink&600 |}}

By using principles in that way, they become a vocabulary for talking about design decisions--a real principle //language//.

Sometimes there is a solution which is clearly better than another one. But there are also cases when both solutions simply have advantages and disadvantages without one being clearly superior.

{{ :about:argument_bad.png?nolink&600 |}} 

In such a case it is necessary to realize that this is the case and abort the discussion which would not provide any further insights.

{{ :about:argument_good.png?nolink&600 |}}

Thinking in principles helps recognizing such situations. In such cases the disagreement is not about which principles are relevant or how they are applied. Rather there is disagreement in how to weight the principles. Some developers will find certain principles or aspects more important than others. As long as the weighting is not based on requirements, it is a matter of personal style.

This can also be taken further. Not only developers have their personal styles of design, there are also typical styles of teams or software projects. In one team or project a certain set of principles may be considered the most important while in another team or project a different set of principles is preferred. This connection can be used to explain the style to a new team member.

{{ :about:new_bad.png?nolink&600 |}}

{{ :about:new_good.png?nolink&600 |}}

Lastly principles can also be used for documentation purposes.

{{ :about:documentation_bad.png?nolink&600 |}}

{{ :about:documentation_good.png?nolink&600 |}}

Documentation does not mean that there needs to be a heavy-weighted design document. A typical case of documenting or communicating reasons for design decisions are commit messages:

{{ :about:commit_bad.png?nolink&600 |}}

{{ :about:commit_good.png?nolink&600 |}}