The relationship between requirements and code in code

Question

I am looking for an easy way to include requirements / release information and source code. The fact is that the developer should be able to find any artifacts created by this version or CR in a simple way. The idea I have is to introduce a new annotation to indicate any new class (I'm not sure if this is good for any new method), for example:

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

Do you have any other ideas? Maybe you are already using something similar?

Take care Marcin

Answer 1

IMO code is the wrong place for this 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 several requirements:

• Users must be authenticated in order to access the system.
• Users can use biometric authentication instead of auth password
• For minor users, parents or something like that should be allowed.

All these requirements were added at different points in time in different versions of the software. Class level annotations, or even method level annotations, are not enough to efficiently match code requirements. You must use the code line level annotation. Of course, this is impractical.

The right way to do this is to follow a few guidelines when using the source code repository and bug tracking:

• 1) Each requirement corresponds to one or more problems in the tracker buffer
• 2) Each commit message starts with a corresponding problem key, for example, "PROJ-123 is a nice feature"
• 3) When you make a release (which means increasing your version of software), you inform the tracker about errors that these problems have been fixed in this version.

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

If you need to know all the code that was created for this requirement, contact the source code repository (the filter is fixed with a log message)

If you need to know what is the requirement for a given line of code, go to the source code repository. GIT and SVN have a “blame” command that will tell you, for a given file, for each line of code who committed it, when and a commit message (which will have a problem number if everyone on the team is a good boy). Thus, it will work as a hypothetical annotation "code level".

Using “commit commit” can help you fulfill rule 2) in your organization.

Maven has some degree of integration with JIRA and other bug trackers, and maybe this can help automate # 3. But I never used it. But if he does not do what you need, you can always ask for more :-)