I’m concerned that this article will mislead some developers into bad habits.
Writing documentation before tests for example is only sensible if that documentation is transitory, a token of conversation between you and your pair (I’ll take it as read you’re pair programming all the time).
Rather than documentation though, it’s often better to write Acceptance Criteria, something akin to Cucumber tests, and use those as your tokens of conversation. Test Driven Development latterly Behaviour Driven Development is all about ‘Growing Software Guided By Tests’, the design to your system emerges through those expressions of behaviour that compromise your test suite. Writing documentation up front, in the manner described in this article could easily lead to you pre-determining your implementation, which can result in YAGNIY, non-dry code.
Writing documentation for private methods is also contentious. Ideally you want internal code to be self documenting, in the way you write the method signatures and split up your responsibilities. Documentation on internal methods can dissuade developers from refactoring, something you absolutely don’t want to do. (Pairing, peer reviews and a good SCM system should ensure refactoring only have positive impact).
Documentation is definitely useful, the Rails and Django projects are great examples of where it’s proved how really valuable it is. Approach it wisely.
Anthony Green
I’m concerned that this article will mislead some developers into bad habits.
Writing documentation before tests for example is only sensible if that documentation is transitory, a token of conversation between you and your pair (I’ll take it as read you’re pair programming all the time).
Rather than documentation though, it’s often better to write Acceptance Criteria, something akin to Cucumber tests, and use those as your tokens of conversation. Test Driven Development latterly Behaviour Driven Development is all about ‘Growing Software Guided By Tests’, the design to your system emerges through those expressions of behaviour that compromise your test suite. Writing documentation up front, in the manner described in this article could easily lead to you pre-determining your implementation, which can result in YAGNIY, non-dry code.
Writing documentation for private methods is also contentious. Ideally you want internal code to be self documenting, in the way you write the method signatures and split up your responsibilities. Documentation on internal methods can dissuade developers from refactoring, something you absolutely don’t want to do. (Pairing, peer reviews and a good SCM system should ensure refactoring only have positive impact).
Documentation is definitely useful, the Rails and Django projects are great examples of where it’s proved how really valuable it is. Approach it wisely.