Basically, each log will have something that is consistent and distinct about it and that gives advantages:
It can make tests more robust and maintainable. Instead of checking for the text of the log (which we change over time to increase clarity), our internal tests can check for the code. We decrease the amount of times we need to update tests.
It can make logs easier to document for the same reason.
It can make communication with users easier. They have a piece of information that is very clear and specific to look up in the documentation or to pass on to us.
Details
Each code will start with ALK and be followed by 4 digits. For example, ALK0023.
The numbers will simply be sequential, regardless of the type of log. The research we've done indicates that categories are too fuzzy and change too much over time.
The reports should show numbers for errors or warnings, but we'll have to discuss more about the other types of report items. For example, variable row descriptions shouldn't have codes in the report.
The logs might start with emojis just before the code.
A code like that can look alarming with no context and users might assume that every log with a code is an error (so, all of them). If we include a clear visual hinting at the type of log, that can immediately show what's going on.
The emojis should be as universal as we can make them. Avoid emojis like š because those are very different between cultures and countries. Facial expressions are better, but if we use faces for them all, it will be hard to tell them apart from each other with a glance.
The emojis should avoid increasing blood pressure. An ā is stressful to see.
[The emojis should be supported by the systems that are going to display these messages. We'll see how that goes.]
Include the text description of the log - ERROR, WARNING, INFO, SUCCESS, or DEBUG (English for now).
Include any additional info about where the message came from. E.g. "setup", "run", "takedown".
Then comes the message and possibly additional data.
Supplementary tools
Additionally, it's hard to keep track of what new code to add next, so include a way to:
Get the highest current code number
Test that we haven't duplicated any codes
Test that we haven't skipped any codes
Add these to our automated internal tests to catch mistakes.
Reasons
Basically, each log will have something that is consistent and distinct about it and that gives advantages:
Details
ALK
and be followed by 4 digits. For example,ALK0023
.Supplementary tools
Additionally, it's hard to keep track of what new code to add next, so include a way to:
Add these to our automated internal tests to catch mistakes.