{"id":111,"date":"2024-03-26T18:48:00","date_gmt":"2024-03-26T18:48:00","guid":{"rendered":"https:\/\/permutationcity.co.uk\/bp\/?p=111"},"modified":"2024-04-28T12:05:46","modified_gmt":"2024-04-28T12:05:46","slug":"when-to-warn","status":"publish","type":"post","link":"https:\/\/permutationcity.co.uk\/bp\/2024\/03\/26\/when-to-warn\/","title":{"rendered":"When to warn"},"content":{"rendered":"\n

If the software you’re developing has a problem then you want to know about it.\nWe use log messages at runtime,\nbuild messages at compile time and we can run extra tools to tell us even more about our code.\nHowever there can be so many messages they you don’t end up reading them, at least not the ones that count.<\/p>\n\n\n\n

Fatal errors<\/h2>\n\n\n\n

I like fatal errors.\nThat is, I don’t like getting fatal errors but it’s much better than spending days tracking down a bug.\nAs this is a fatal<\/em> error is it still a warning?\nI’m going to say yes.\nThe message attached is the warning and there should be an attached warning<\/em>.<\/p>\n\n\n\n

I’m use to having a set of logging functions like this:<\/p>\n\n\n\n

void log::Debug(const std::string& format, ...);\nvoid log::Info(const std::string& format, ...);\nvoid log::Warning(const std::string& format, ...);\nvoid log::Error(const std::string& format, ...);\nvoid log::Fatal(const std::string& format, ...);<\/pre><\/div>\n\n\n\n
And that last one logs a message and exits the program.\nYou might come at it from the other direction and have exit functions like this:<\/p>\n\n\n\n
void ExpectedExit();\nvoid UnexpectedExit(int code, const std::string& format, ...);\n<\/pre><\/div>\n\n\n\n
I wouldn’t just use exit<\/code> because then someone can forget to use a message.\nGenerally speaking if someone can do something they are going to do it at some point.<\/p>\n\n\n\n
This is when something catastrophic has gone wrong and continuing makes no sense.\nWhat this means depends on the product.<\/p>\n\n\n\n
Recently I’ve been working on batch processes which powered a web service.\nThat meant exiting made sense even with fairly simple things such as the configuration file being missing.\nThe end user wasn’t able to touch the configuration directly so the file really should have been there.\nThe web front end was still there to interact with the user.<\/p>\n\n\n\n
If your process is interacting directly with the user then a fatal error is less useful.\nIdeally if something goes wrong you tell the user with a status message or dialogue box and continue,\na warning can go to the log file as well.\nHowever depending on what the “something” is continuing may or may not be possible.\nAgain, to avoid wasting time tracking down bugs it’s better to detect an error and exit than just crash.<\/p>\n\n\n\n
Warnings everywhere<\/h2>\n\n\n\n
It helps if the team has a clear idea of what each logging level is used for.\nWhat is the difference between log::Debug<\/code> and log::Info<\/code>?\nMaybe the first has low level details including variables and the second shows more general program flow.\nWhat is the difference between log::Warning<\/code> and log::Error<\/code>?\nMaybe the later is the underlying problem and the former is the chaos that is caused.<\/p>\n\n\n\n
It’s fairly common to end up drowning in messages.\nBe especially careful with log::Warning<\/code> and log::Error<\/code>.\nIf you it’s possible do some extra processing to weed out red herrings.\nIdeally these messages should really mean something.\nSeeing one should make you stop and investigate… otherwise you run the risk of habituating to them.\nOnce you’re use to warnings it’s very easy to miss new ones when they really matter.\nThis is where log::Fatal<\/code> has an advantage because it’s impossible to ignore.<\/p>\n\n\n\n
I think the most common occurrence of this is with build systems.\nA lot of systems, especially legacy systems, have so many build warnings they cease to have meaning.\nIf possible start your project by switching on “warnings as errors”.\nThis will force you to go the extra step and keep a clean build.\nThat means potential problems that do appear will be caught immediately.\nOf course, it normally means jumping through some extra hoops in your code to satisfy the compiler.\nIt’s a bit of extra work but rarely hard.<\/p>\n\n\n\n
A particularly annoying situation here is changing or updating your compiler.\nAll of a sudden code that was “clean” is now flagged as problematic.\nI didn’t like some of my recent experience with automatic compiler updates.\nIt meant that whomever was updated first suddenly had a broken build.\nMixing their original branch with this fix can be confusing and\nmay end up duplicating work if someone else hits the same update.\nReally fixing the build in this situation is a separate task.\nIdeally it could be noticed and scheduled rather than dropping in unexpectedly.<\/p>\n\n\n\n
And now SonarQube<\/h2>\n\n\n\n
SonarQube<\/a> is my original inspiration for this post.\nIt’s a code analysis tool that can integrate with your build system and give you feedback on\na variety of problems, both actual and potential.\nIn many ways it’s good although\nI don’t always agree with every rule<\/a>.\nImagine a code review but a knowledgable but pedantic colleague.\nMaybe a bit irritating on minor issues but helpful in the long run?<\/p>\n\n\n\n
My experience was that it’s a bit like the situation with automatic updates.\nIn an instant the codebase went from being warning free to having hundreds of issues.\nNo bugs or security issues but many code smells.\nIt’s good that we could know about them but very distracting that we suddenly did know about them:<\/p>\n\n\n\n