A Theory

1 minute read

I believe most programmers familiar with open source software would agree the documentation is usually lacking. Some attribute it to a lack of writing ability, laziness, lack of priority, and various other negative reasons. I suggest it is actually for a good reason.

The source is the documentation. Most additional documentation is redundant and misleading.

Whenever creating a complicated program, the author runs into conceptual road blocks. A time where you think the code should do one thing but it does something else. Scientific theory would suggest we conduct experiments to try and discover the true behavioral rules. With open source we don’t need to do that. The rules of the universe are at our fingertips. We can read the rules directly and know not only the true behavior but if there are comments, we even know the intent. Documentation may point you in the right direction but the code is the master.

Documentation is a substitute for the source when one doesn’t have access to the source. Unfortunately, when dealing with closed source software such as some of the Apple frameworks, all we have is the documentation. This means there is no alternative to experimentation when the code behavior does not match expectations. Sometimes this might be due to an undocumented bug. Sometimes it is due to a conceptual misunderstanding on the part of the programmer. For example, I have been wrestling with a Cocoa Autolayout problem. If I had access to the source, it would be trivial to determine whether it was a bug or misunderstanding and resolve cleanly. Instead I created a workaround. The documentation is excellent but wrong in some way. Most likely due to a bug.

The source is (almost) never wrong.

Updated: