javarequirementstracer
Annotation Type Requirements

@Target(value={TYPE,METHOD,CONSTRUCTOR})
@Retention(value=RUNTIME)
public @interface Requirements

Use this annotation to annotate your code with requirements labels for traceability purposes.

Guidelines:

• Typically all exported (ie. public/protected) types (ie. classes/interfaces) in the presentation and service layer of your system should have this requirements annotation, linking it to the requirements. Tracing them to lower layer types, general and helper classes, etc. is easy with any IDE. So those lower layer types, etc. don't have to be annotated.
  Optionally the model classes in your model subpackage can also be annotated linking them to the requirements domain model.
• Annotate types specific to a requirement only. Prefer not to annotate general, helper and util classes. For they would require a long unmaintainable list of many requirements.
  NB.1. Helper classes should not be part of a package-API anyway (ie. should not be exposed). JavaRequirementsTracer does not include package-private types in its untraceable section. Often the easiest way of removing a type from the untraceable section is by making it package-private (ie. package implementation details should not be exported: encapsulation)!
  NB.2. Exported types that need to be part of the package-API but are not linked to any requirement can be annotated with @SuppressTraceabilityWarnings.
• Prefer annotating a method over a type.
• All requirements labels known should occur at least once in the main code (100% requirements coverage). And all exported types should have at least a @Requirements or @SuppressTraceabilityWarnings annotation (100% code coverage).
  NB. This code coverage is not be confused with test coverage which is often also called code coverage.
• One could annotate the corresponding unit test classes (see JUnit) also, but usually that is not of much use.
  NB. Unit Tests are white box tests, ie. the test classes reside in the same package as the tested classes. They can access any member (even private ones if needed) of the tested class.
• If system testing is done through code (the prefered way!, eg. using JUnit, JWebUnit, etc.), 100% requirements coverage and 100% code coverage should be achieved for the system test code also.
  NB.1. System Tests are black box tests, ie. the test classes reside in another package then the tested classes. They access the exported package API only. Since system test code resides in its own specific packages, one can generate specific reports for main code and system test code coverages, by specifying different packages to scan for requirements labels.
  NB.2. Main and System Test code must have separate parameters files but should have a shared labels file.
  NB.3. Typically one would write a test class or test method per test scenario. The name of the class/method should reflect the scenario. Multiple test classes/methods (ie. multiple scenarios) can be related to the same set of requirements.

Reporting (see JavaRequirementsTracer):

• A type is considered annoted with @Requirements if its type or at least one of its constructors or methods is annotated with it.
• Requirements annotations are not inheritable by subclasses and implementations.

Author:

Ronald Koster

Required Element Summary

java.lang.String[]

value The set of requirement labels implemented by annotated class, method or constructor.

Element Detail

value

public abstract java.lang.String[] value

The set of requirement labels implemented by annotated class, method or constructor.

Requirements labels refer to requirements documents. Usually Use Cases (UCs) or Supplementary Specifications (SuppSpecs). They can refer to a whole document (doc) or only a part of it. In the latter case the requirements document itself is usually annotated (aka. tagged) with detail labels (aka. tags) in the text itself, which can be used directly as requirements labels. The format of the tags used should be as agreed with the requirements specifiers.

Examples:

• UC01: Refers to UC document of UC 01.
• UC01.2: Refers to flow 2 of UC document of UC 01.
• UCD-MAX-AGE: Refers to tag UCD-MAX-AGE in the requirements docs (it is unknown which doc from the tag itself, apparently the tag can easily be found in the requirements docs).
  NB.1. UCD = Use Case Detail.
  NB.2. It is better to use self-explanatory labels/tags like this one instead of numbers. From this label one can tell it has something to do with the max age of something (what is usually clear from the context). Whereas UCD-137 is totally not self-explanatory, it can mean anything.
• SUP-ACC-LOCKED: Refers to tag SUP-ACC-LOCKED in the SuppSpecs. It has probably something to do with accounts being locked or not.

WARNING: Do NOT incorporate requirements document version info in the labels (bad practice). Instead, in case different labels are needed to mark different requirements in different versions, use tags (as described above) in the requirements document itself to uniquely mark those requirements. Also, never reuse a label/tag for another requirement. A new requirement should always get a new label/tag, to ensure the uniqueness of all labels/tags.