Basic logging guidelines
Next to unit testing I believe in logging to improve the quality of an application. Instrumenting code with logging (or tracing for that matter) should be an integral part of writing production code. Yet, I’ve often found it not to be the case or that what got logged only made sense to the developer who wrote the entry.Not logging implies that debugging the application outside the development environment is largely based on guesswork. That’s interesting given that most applications spend the majority of their life running outside the development environment.
Life in the sandbox
I suspect the absence or low quality of log statements can be, at least partially, explained by developers not finding them useful during development. The debugger available there is generally inferior to the print-lining approach of logging. That said, I’d argue that many developers don’t concern themselves enough with how their code behaves in a production environment. Rather than investing a small amount of time in adding log statements up-front, their focus is solely on satisfying functional customer requirements. A related case could be made for exception handling. For instance, rather than asserting the validity of an argument up-front and throwing an appropriate exception, the code may later fail with a NullReferenceException. Not throwing the exception up-front, close to where the actual error occurred, one will have a hard time tracking down the issue. Especially since a stack trace with symbols and line numbers is rarely available in a production environment.
For someone having to resolve the issue, almost any clue as to the cause would be most welcomed. Without a clue that someone would walk around in the dark in the hope of stumbling into a solution.
End users aren’t the only users
As software developers we have to acknowledge that end users aren’t the only users of our software. System administrators, developers, and the like should also be factored in during development. Especially since the cost of instrumenting code at key places, early on, doesn’t add significantly to the overall development cost. Focusing on what can go wrong and communicating it well saves time, money, and frustration down the line. And as a bonus you might create better self-documenting code. That said it’s important to strike a balance between logging too little and too much information. A log should be detailed enough to reveal patterns of use. Ideally, the log should read like a story with short sentences detailing what’s about to happen, what did or didn’t happen, and possibly why.
I’m not suggesting that we turn logging into a runtime version of literate programming. But simply that sufficient contextual information be provided, i.e., instead of logging “URL = ‘bugfree.dk’”, consider the more elaborate “Retrieving URL for indexing: ‘http://bugfree.dk’”.
Keep your statements clean
On the other hand, log statements shouldn’t be immune to the DRY principle. So make sure to have the logging framework automatically capture common bits of contextual information, such as the date and time of the entry and the class and method within which the log statement originated. On a similar note, don’t explicitly log when a method is entered or existed. Instead, treat such a case as a cross-cutting concern and take an Aspect Oriented approach to logging it. Lastly, not every method requires (extensive) logging. Figuring out when and what to log is key. Debugging the application, fixing bugs, and experience should provide guidance into what’s useful to log.
No comments:
Post a Comment