Connection between requirements and code in code

Question

I am looking for simple way to connect information about requirement/release and source code. The case is that developer should be able to find any artifacts created given release or CR in easy way. The idea I have is to introduce some new annotation to mark any new class ( I am not sure if it is good for any new method) for example:

@ArtifactInfo(release="1.2" cr="cr123")

Do you have any other ideas? Maybe you use already something similar?

Take care, Marcin

Ambulacrum

Depending on your etiqquete and development habits, if you're the kinda guy that doesn't update docs regularly this will end up hurting more than the benefit it brings... i don't wanna imagine syncing these to SVN after a month of rapid development and zero comment/javadoc updating. though it's a decent idea, maybe you should just tie certain features to svn revisions? – Mat

Javadoc already have @since tag for classes – Ludovick

I have been using @since. I was just wondering if there is something better... – Ambulacrum

This seems like a task better relegated to the CM repository rather than in the code itself. CM provides very specific history and the check-in comments can include a reference to the specific requirement(s) related to the code that has been changed/added. Using an integrated ticket system like Trac or Redmine makes it very easy for any developer to see changes based on information such as this. – Pelage

Answer 1

IMO the code is the wrong place for that kind of information.

Take a look at the imaginary code below.

class Authenticator {

    login(String username, String password){
        User user = retrieveUserFromDatabase(username);
        throwIfWrongpassword(user, password);
        verifyUserAge(user)
    }

    void throwIfWrongpassword(User user, String password){
        //throws AuthenticationException if password is wrong
    }

    void verifyUserAge(User user){
        //verify that user is above 18 or account is authorized by a parent
    }

    void biometricLogin(String username, BiometricImage bioimg){
        User user = retrieveUserFromDatabase(username);
        verifyBiometricImage(user, password);
        verifyUserAge(user);
    }
}

This is the result of a few requirements:

• Users must authenticate to have acces to the system
• Users can use biometric authentication instead on password auth
• Underaged users must be authorized be parents or something like that.

All those requirements were added in different poins of time, on different versions of the software. A class-level, or even a method-level annotation won't suffice to effectively map requirements to code. You'd have to use a "line of code"-level annotation. Of course, that's impractical.

The right way to do that is to follow a few best practices when using the source code repository and the bug tracker:

• 1) Every requirement corresponds to one or more issues on the bug tracker
• 2) Every commit message starts with a corresponding issue key, like "PROJ-123 - a nice feature"
• 3) When you do a release (meaning, incrementing your software version), you tell the bug tracker that those issues were fixed in that version.

If you need to know what requirements were implemented in what version, ask your bug tracker.

If you need to know all the code that was produced for a given requirement, ask your source code repository (filter commits by log message)

If you need to know what is the requirement for a given line of code, ask your source code repository. GIT and SVN have a "blame" command that will tell you, for a given file, for each line of code, who commited it, when, and the commit message (which will have the issue number if everyone on the team is a good boy) - So this will work as that hypothetical "line-of-code"-level annotation.

Using "commit hooks" can help you enforce rule 2) in an organization.

Maven has some degree of integration with JIRA and other bug trackers, and maybe it can help automate #3. But I haven't really used it like that. But if it doesn't do what you need, you can always ask for more :-)

Pivotal

Tony, thanks for this complete solution. Some of things are already used by me. It seems I just need to order our process and then we will be able to track changes more effetively. – Ambulacrum

The httpunit project follows some of the best practices mentioned here. In the subversion commit message the tracker ids are used and later picked up by this script: httpunit.svn.sourceforge.net/viewvc/httpunit/trunk/httpunit/… The result is shown in the release notes: httpunit.org/doc/release_notes.html and the tracker comments usually point back to subversion. So tracing is from requirements to code. In principle tracing back would be possible with this information. – Fuze