It is more important to document the reason why, than what, so that when things change, you empower someone else to make a better decision.
3 Replies to “Intent Over Artefacts”
Comments are closed.
It is more important to document the reason why, than what, so that when things change, you empower someone else to make a better decision.
Comments are closed.
I would argue that it is not only pointless, but actively dangerous, to document the “what”. The what changes, and frankly people should be able to figure out the “what” anyway. The “why” (and, for that matter, the “WTF???”) are key. Unless you are making a user manual, of course. 😉
I totally accept with you, Patrick. I started hating comments in source code because most of them say what the code does rather than why it is doing that. As the comments what is the coding, when someone changes the code they also need to change the comment (DRY principle anyone?!?!?). Most of the time the comment is not updated and it does more damage than not being there in first place.
Thanks for your comments.
Robert I do not believe that it is totally pointless to document the “what” – sometimes this is a more scalable method for bringing more people on board a project with conventions and as long as the “what” can be supplemented by a conversation describing the why (the context), it can be quite powerful, but on the whole I agree.
Siva, I like it most when people try to avoid writing comments, and focus on writing more readable code. I suppose my post was just a reminder of a mantra I like to use when I do lots of different things (writing code, writing documentation, talking with people). Looking back it probably should have read, “It is more important to communicate the reason why, …” as I think it applies to more than just writing.