Let's imagine we are working on a C project, and we want to keep a sort of documentation of what we implemented, what achieves, and if it has been tested by some code. Trace is a tool that aims to provide such functionalities in an organic way.
The vision behind Trace is that planning and documenting your code shouldn't feel like adding layers and layers on top of your projects. Maybe it could feel like a natural part of the project itself. So I thought of building a C library that you can compile with your own source files, and automatically offers you enough tools to achieve:
- requirements definition
- a summary of requirements coverage
- tests definition
- test coverage
Let's say we need to implement a function, for sake of simplicity, that adds two numbers. `
/* add.c */
int add(int a, int b) {
return a + b;
}
The idea with Trace is to be able to decorate this function with something like:
/* add.c */
// @implements REQ01
int add(int a, int b) {
return a + b;
}
Such decorator tells us that this function exists because there is a requirement somewhere that defines what the code should do. We could then define the requirement itself:
/* add.c */
/*
@req REQ01("The system should be able to add two numbers.");
*/
// @implements REQ01
int add(int a, int b) {
return a + b;
}
The next step would be also to have some test that makes sure that the requirement is satisfied:
/* add.c */
/*
@req REQ01("The program should be able to add two integers.");
*/
// @implements REQ01
int add(int a, int b) {
return a + b;
}
// @tests REQ01
bool test_add() {
int a = 2;
int b = 2;
return add(a, b) == 4;
}
This simple examples showcase the core concept of this library, and the essential blocks that it offers . Once you compile Trace alongside your source code, it automatically parses these decorators and generates some files for you:
ID Description Tests Implemented REQ01 "The system should be able to add two integers." 1 Yes
- Total requirements: 1
- Implemented: 1
- With tests: 1
What is the value of such documentation? You have an abstracted view of what you're doing, and you can focus on what you're doing rather than how. Plus, you get a quick overview of how many tests you currently have per requirement.
You just need to copy and paste trace.h and trace.c, and compile them alongside your source code. For every file you want to annotate, use the macro TRACE_THIS(); and the tool will produce for you a markdown.
This project is currently explorative rather than stable. Stay updated for future releases to see this project grow. Good programming!