Sunday 9th October, 2011
11:30am to 12:30pm
Does: “Everything needs to be documented!” sound familiar to you? Do you like the idea?
This talk aims to make a case for the point that forcing developers to document every single piece of code will not result in good documentation. It will generate superfluous documentation and even impair the code quality!
It is really easy to write docs for bad code because short and indescribable named functions need to be explained while code that clearly communicates its intentions and actions does not.
The question discussed include points like:
Further discussion where documentation is really needed and showing some common documentation “refactoring” patterns. By explaining ideas like “replace comment with function call” and “replace description with variable” the talk aims to save the time of every developer. Spending it once while writing the code and then saving the time of everyone involved by not making them re-read documentation that only tells them what they should already be expecting by reading the class and function names.
I'm a magic __method(); Well, a Software Engineer @ResearchGate interested in tdd, ops, php, CI, (no)sql and so on. Also an enthusiastic gamer bio from Twitter
Sign in to add slides, notes or videos to this session