In an Agile environment we try to creat “just enough documentation” and “just enough architecture”. To achieve this we need our source code to become a part of the documentation.
At this point most developers will jump in the air and all others will go “oooh NO”. The reason why we have such reactions is because developers think they don’t need to do anything and all others think the code is not readable. I must say that in the past the last argument was pretty much true, but all of this has changed or it needs to change fast.
Developers need to start creating more clean and readable code. The first reason why they need to do this is because the code gets better and is easier to maintain. The second reason is Developers need to be aware that the source code is part of the documentation, because they are not the only ones that need to be able to read it. But it’s not only the Developers that need to change, others in the project need to accept that the source code is a part of the documentation as well.
Bad example, we can all conclude that this peace of code is not easy to read.
Good example, I hope we all agree when I say that this code is easy to read and to follow.
Both the first and the second example do exactly the same but the second one can be understood in seconds where the first one first needs to be interpreted. In the second example I left the “detailed” code out on purpose because it is not about the detailed code. When we talk about documentation we want to know more about the flow and the relations not the details. If done correctly the details should already be tested and can be reviewed by looking at the test cases.