This question already has an answer here:

I am working on a number of maintenance projects and I always include requirement/issue number/code in the the comments whenever I am adding or changing code. In such way I provide traceability from requirements to the code and back. My experience is that such effort can be of really great help for furhter maintenance, especially if requirements are changing or are updates due to initial inconsitencies in the requirements.

However, I have seen source code from other projects which have no comments at all and I can only guess what part of the code is implementing what requirement.

What is the good practice in traceability of requirements and comments?

marked as duplicate by gnat, Community Jul 10 '17 at 9:52

This question has been asked before and already has an answer. If those answers do not fully address your question, please ask a new question.


Since everything in a code base is ultimately due to some requirement or other, this tends to litter code with pervasive and even multiple issue ids in every section. I much prefer to have such references in the commit comments, which leaves the code base cleaner for easy reading.

The connection to requirements documents can still be made by using the history function of your revision control system, and since code reading is much more common than resolving the question "Why and when specifically was this functionality written?", it's a good trade-off to require an extra step for the rarer task while leaving the more common one unencumbered.

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