I have a rating engine (it is basically an algorithm) which when I started had no formal documentation. We have created a functional specification/decomposition which is our business level document but now I need something more technical (a technical specification).
What I am struggling to understand is what that document looks like, what format it should be in and to what level of detail we should go into.
We are in the process of commenting all of the code. We also have a rough document called a Blueprint which reflects the flow of the model and is written in pseudo code. Is the combination of this blueprint and the model comments sufficient as a Technical Specification?
The goal of this kind of specification is to help incoming workers to dive into the code. It must also help experimented workers to hold a clear overview of the project.
You can change your blueprint for a UML diagram, particularly an activity diagram in your case. This offers a (more or less) standardised way to visually represent your workflow. It shows the actions done on the algorithm, the choices made, the options available for each choice, the loops, etc. You can also show the beginning and the end of your process, exhibit the elements required or produced by it, and highlight some points thanks to comments.
At a lower level, intelligently comment the code is always a good idea. Generally, one must specify, for each piece of code (function, method, class, …)
- Its inputs, and which properties they must respect (the list must be sorted, etc.);
- Its output;
- What happens in particular cases (an empty list, an invalid input, etc.). Indicate the raiseable exceptions, if your language support them;
- Its side effects (ideally it should not have any). Typically the read/write from/to files, network, etc.;
- If it is thread safe. That is, if its state can be changed during its execution by an external entity. Check for instance if the list given as an input can be changed externally. Thread safety is very important in a multi-threaded environment, of course, but this is also a sign of quality. The developers should be very careful when they use an unsafe piece of code.
- Its time and memory consumption, w.r.t its inputs. The external users want answers to questions like “Can I give a (very) big list to this function with no major computation time issue?”.
- The context in which it must be used, if this context can affect its behaviour (ideally it should not be the case since the only influencing factors should be its inputs).
- If required, how to automatically build and test it.
Use tools allowing you to add those comments in your code, and being able to automatically generate reports in a separated document. See javadoc or doxygen for instance. Thanks to these tools, you can update the information in the same time you change your code, and get an always up-to-date separated documentation.
Complete the specifications by automated tests, and consider them as part of the documentation. Tests describe what should be the code behaviour in normal situations and exceptional situations.
Your engine should then be considered as a collection of entities communicating together. You know how each entity works, how entities must act together and how they act in representative situations.
Note this is not an advocacy of OOP, since the “entities” can be functions (in functional programming), structures, classes (in OOP), etc.
1
Don’t write comments just for the sake of it. Comment public API, comment REGEX expression, comment something truly difficult (rare to come across with all the frameworks and tools out there). I don’t think that this is a solution to your problem.
Write a document for a person who knows nothing about what you are doing. The document should explain why you are doing this, how you are doing this and how it can be tested (validated).
Find somebody who knows nothing about what you are working on. Give them the document. If it makes perfect sense to them, then you’ve done a good job, otherwise go back to the drawing board.