How do you track existing requirements over time?

Question

I'm a software engineer working on a complex, ongoing website. It has a lot of moving parts and a small team of UI designers and business folks adding new features and tweaking old ones. Over the last year or so, we've added hundreds of interesting little edge cases. Planning, implementing, and testing them is not a problem.

The problem comes later, when we want to refactor or add another new feature. Nobody remembers half of the old features and edge cases from a year ago. When we want to add a new change, we notice that code does all sorts of things in there, and we're not entirely sure which things are intentional requirements and which are meaningless side effects. Did someone last year request that the login token was supposed to only be valid for 30 minutes, or did some programmers just pick a sensible default? Can we change it?

Back when the product was first envisioned, we created some documentation describing how the site worked. Since then we created a few additional documents describing new features, but nobody ever goes back and updates those documents when new features are requested, so the only authoritative documentation is the code itself. But the code provides no justification, no reason for its actions: only the how, never the why.

What do other long-running teams do to keep track of what the requirements were and why?

Answer 1

Unit Tests are your friend.

One of the main reasons for writing unit tests is to protect your code against future changes. If you have a unit test attached to each required behaviour, then there is no chance that a future enhancement will cause the code to do "weird stuff".

Interestingly, unit tests also become the living documentation that programmers otherwise find so hard to maintain. If you have a unit test called DisableAccountAfterThreeWrongPasswords, then the requirement is captured right there. If you change it in the future to four wrong passwords (say), the test will fail and you will be forced to update it - and presumably the test name as well.

Of course, adding unit tests into a complex legacy system is not easy, and the code usually needs to be architected in a way that makes this feasible. I would start by refactoring the most "rigid" parts of your code and creating tests as you refactor, and then grow your test set as you continue to enhance the application.

Answer 2

I am hoping you have some VCS (preferably DVCS) - the commit messages and change logs are a great starting point.

Create Internal Wikis - documents are too heavy weight to be edited and maintained. (Sharepoint 2010 is an exception though, if used right). Strive to keep these updated (it doesn't take much effort) for high level design decisions.

Have a good bug/feature database like JIRA and keep that updated on current work. The best part of this is the history that is provided. Create tasks / bugs by copy pasting mails / from team meeting notes.

Add a ton of code comments, with references to the above bug database.

Review your code using a code review tool, maintaining the cr comments there. Link the JIRA task to this, hence ensuring you can remember your code decisions.

Backup everything! :)