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

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 🙂