You comment your code, you log your commits and you document your database, architecture and other project stuff. But do you log and document your decisions?
Why should i do that?
You always should program for the next developer! So you have coding conventions, commit logs and comments in code for it. But even the cutest code can’t help the next developer to understand why you did the things you did. Commit logs are more useful in this context but usually very short and some data is missing.
When i look at code from others, some questions are often in my mind:
- Why he did it like that?
- It looks like an error but works?
- Maybe it was intendiert to work like this?
- Someone surly thought about that?
You cannot answer this questions alone, you walk over to the developer who made it and talk about the questions. Often he can’t really remember the topic and you hear answers like: “I am not certain but i think we did it like that because someone said something …”. Hmm okay, who is “someone” and what was the argument for or against it?
If you can figure it out, good. But usually you have to discuss the whole topic again and make a “new” decision.
You have to do so also if the developer is not available currently or he left the company.
What is a decision in this context?
It can be a technology decision like using frameworks or libraries. A decision in the area of software architecture or a simple coding decision. You every day make many of these, you can’t document all of them, but if you have to discuss it with one or more of your peers it’s worth to document the outcome.
Often decisions have to do with business logic, usually your product manager have to document such things, but to be on the safe side you should write it down in your documentation too.
How should i do that?
Document positive and negative decisions, the yea and ney sayers and their arguments for or against the topic and of course the date when you decided it. Some examples for larger and smaler decisions in prosa:
- 2014/02/03: Let’s add a field “productId” to database-table “User”. @DerFichtl, @TylerDurdan think it’s not a good idea but the alternative would be complicated and hard to implement.
- 2014/02/03: Flatrate vs. PPV: We implement flatrate, PPV is a nice idea but to early in our situation. @MrBlack, @MrPink, @MrWhite are for it. @MrYellow is doubtful because of competitors have already PPV. @MrBrown knows it’s more risky but thinks PPV would be the better choice.
If you like a more structured way to document such things, try a table.
|2014/02/03||We make something really strange in this sprint!||
What happens then?
Documenting things is only useful if you use it later for other decisions. It should be possible to find all your notes about a specific topic. If you discuss a new decision, look in your documentation if you have already talked about before, maybe it’s already clear what to do, maybe a new argument arise and you have to change your decision from past.