4

We have an existing code base which has been developed to meet the needs of most of our clients, which has accumulated features and bug fixes as they were needed and as projects developed universally useful features.

Right now, we're running into the problem that there's no real documentation for its capabilities outside of the code itself, and on larger jobs it can mean that it's difficult to determine what should be included in the scope of work.

How would you approach writing a defined spec for an existing application or framework?

Improve this question
3
  • 1
    Spec? What spec? – Wyatt Barnett Apr 27 '11 at 15:37
  • Hack and Slash it. If you are lucky the software actually works the way it was suppose to. In my case it works like swiss cheese after a old west shoot out. – Ramhound Apr 27 '11 at 15:59
  • @Ramhound - Correct me on this if I'm wrong, but you're saying it works, uh, well? Because swiss cheese is supposed to have holes in it? And the shootout puts more holes in it? – Dan Monego Apr 27 '11 at 16:06
7

Doing it right now, actually.

Test-Driven Reverse Engineering.

  1. Write some kind of overview as best you can.

  2. Create minimal unit test cases for each component. Minimal. Enough to show that the component does one thing correctly.

    If you already have unit test cases, use the existing cases as the basis for documenting what's really there.

    If you don't have cases, don't just read the code and hope you understood. Memorialize your understanding with a simple test case that proves you and the code agree.

  3. When you get the test cases to pass -- which isn't always easy -- you now know (deeply) what's going on. Document that. Often with a code sample. Often pulled from the test case.

  4. When you find latent bugs, confusion and problems (which you will find) you have unit tests and can refactor.

Start from the most visible-to-the-user features first.

Avoid stuff that involves purely technical details like a data access layer or the way settings and preferences are managed.

Improve this answer
1
  • +1: This situation occurs all too often and this is an excellent approach. You start with the "simplest" steps first—which can occur simultaneously with ongoing development/operations—and once you have those fleshed out you can write the overview, confident that you understand what the system is actually doing. – Peter Rowell Apr 27 '11 at 15:39

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.