Documentation specifies behavior. Not Code.

When developing software architectures one usually plugs together various components whereas many of these components are developed and maintained by third parties. That is, in order to ensure reliable behavior of the new architecture, one needs to respect the specification of the interface of single components when wiring these together. Specification is a guarantee. It usually comes as (auto-generated) documentation. If an interface of a component does not behave as documented (specified) then this is a violation of guarantee. This is a bug which is usually taken seriously by the maintainer of given component (in most of the cases, the code internals get fixed, in rare cases the specification is changed).

In turn, relying on non-specified (undocumented) behavior of a third-party component when using it in the context of a new architecture is quite risky. It can be done, but usually means that one can not follow the release cycle of such third-party component without manual inspection. This is quite a limitation and the general rule is that such a situation is to be avoided.

While the above considerations should be clear to software developers, I am impressed about how many answers on StackOverflow actually provide solutions based on undocumented internals of libraries without providing the corresponding warning. As an aged user of StackOverflow I have seen this quite often. Just now, I got fooled by such an answer myself and really needed to express this:

The documentation of an interface specifies behavior. The code internals don’t. They might change at any time. Please, never provide solutions to problems based on code internals of third-party components without annotating such solutions with a huge warning sign.

Leave a Reply

Your email address will not be published. Required fields are marked *

Human? Please fill this out: * Time limit is exhausted. Please reload CAPTCHA.