How to trace business requirements into program code without going crazy
Growing pains
Consider either a small company with a few dozen employees, slightly less than fully engaged in software development, or a department of the same size in a larger company, fully engaged in software development. There is top management who sets business tasks, there are middle managers who distribute tasks among performers, and there is line personnel, including programmers, regular and leading ones.
When a product or service first appears, it has one single version. Code, as a rule, is written according to tickets from mid-level managers, who at the same time become sages and bearers of sacred knowledge (for top management – about the work of program code, for performers – about business tasks, users, resources, limitations, …) . At first everything is fine: the team is small, the product is intelligible, if someone doesn’t understand something, the person in charge is known and available for direct communication.
Subsequently, top management begins to receive feedback from users and owners, so new business tasks arise that are assigned to middle managers. The product acquires new capabilities, the team develops and grows: someone leaves, someone comes.
The ease with which the company could make changes to the product gradually disappears. The flow of information falling on managers is growing and, as a result, begins to be filtered. The amount of necessary knowledge no longer fits into individual heads, and the sudden departure of such a manager or leading line employee with unique knowledge and his replacement with a person from the street can become a pain for the entire company.
The code becomes a mystery to the programmers themselves, not so much in terms of the algorithms, but in terms of the business processes supported by this code. Over time and, especially, with the departure of employees, understanding of the motivation for the previously made choice of algorithms, interface design and other decisions is lost.
Formalization of requirements
At some point, top management, and then the owners, begin to realize that their articulated will is lost somewhere: at best, in bureaucratic approvals at the level of middle managers, or even sabotaged. Making changes to business processes and code is becoming more expensive and less reliable, and the race for financial performance and competition only increases stress.
It happens that such companies come to their senses in time and formalize the changes. The company has full-time business analysts who describe top-level requirements in the form of text, tables and diagrams. Sometimes, even for this purpose, it is not Microsoft Office that is used, but specialized requirements development tools. Good requirements development tools allow you to link from lower requirements to higher ones, so that the will of top management, the pain of users and the rationale for functional requirements are traced (traced) to each other.
Middle managers no longer invent change tickets: tickets become a consequence of changes in requirements, that is, differences between versions (baselines) of requirements. This is ideal, but let's assume.
What about the code and programmers? Their hell is not going anywhere. The will of top management reaches the empyrean of middle managers and analysts and… is lost in the abyss between the requirements development tool and the ticket system on the one hand, and the hell of the code repository on the other.
Programmer's Hell
Programmers write comments. Good programmers in large teams provide links to higher-level requirements (functional, architectural, etc.) in the comments so that other programmers, and even they themselves in a couple of years, can understand why the code was written this way and not otherwise.
Why can’t you just copy and paste the requirement into a comment, why do you need to put a link? Because a requirement can change when moving from one version of requirements, one version of software, to the next. Analyzing the impact of changing requirements (impact analysis) becomes easier: you need to find all sections of code that reference the changed requirement.
How to create a link? Modern development tools provide a web link (URL) for each requirement. It would seem that all the programmer needs to do is Ctrl-click on a link in his integrated environment (IDE), and, here it is, the requirement, in the browser window.
But requirements have versions. The code also has versions. Should the link change when the requirement version changes?
If the link (URL) necessarily changes from version to version of the requirements, then moving from version to version in the code means making changes wherever the requirements are referenced. A small bug fix in a minor version will lead to changes throughout the entire code.
If the reference changes only when the requirement itself changes, then two options are possible. The first option: different places in the code will refer to different versions of the same requirement, which is not an option. The second option: if you check the unity of the version of the requirements, for example, with a script in the code version control system (git hook), then you will have to change the link not only in the place of the code that is actually subject to change, but also in every place affected by this requirement. Better, but still a branch of the same hell.
If the link does not change at all, then when working on an old version of the code (for example, when urgently fixing a software error in a product version), the programmer will see the latest version of the requirement when clicking on the link.
It won't work that way. Isn't there a better way? Is it really impossible without an abyss, without an empyrean and hell? So that the will of management reaches to the very bottom, and below they do not feel emptiness and despair.
Without abyss
Dear reader, thank you for reading. I hope that a few of my tips will not ruin your mood completely, but will give you hope.
Write each requirement in a separate file. Start with Markdown format, further complications are possible.
Provide links in code comments as the shortest relative paths from the code file to the requirements files.
Markdown is supported by Doxygen, so write links in comments in Markdown format, and the transition to the requirements will be possible in the browser with the generated HTML.
Store these requirements files in git along with your code. You can create a separate repository for analysts with their own access rights, which will be connected to the code repository as a git submodule. Yes, analysts will have to learn git and write requirements in the IDE.
Of course, you had questions, comments, criticism and curses. If you are not ready to offer me a job, then please comment below the article.
