We’ve all been there, staring blankly at a log file, trying helplessly to make heads or tails of it. More times than not, our heads are spinning so fast that we have no choice but to give up on it. Is it not startling that in today’s day and age where software development models have matured to such sophistication, that we have somehow lost all touch with coding foundations?
Someone once said, “Coding is poetry.” I couldn’t agree more. Good code is much more than just simple text, and we cannot expect to digest its meaning from only one read. Much like interpreting a work of poetry, we must integrate many factors to form an informed interpretation; contexts, language constructs, patterns. However, there is one crucial asset that is intended to assist us in determining the true expression of code; the log file. If the coder followed good principles, the log generated during its execution can help us see precisely what the code is doing and why. This is the story of code. Good code is a piece of poetry while the log file is the beautiful story behind it.
Unfortunately, in recent years, I’ve seen many worse log files. Either people no longer care, or they have forgotten this fundamental principle. And I hear the complaint echoed again and again from many tech leads.
In today’s IT ecosystem, it is becoming common to spend 50-60 hours a week working. But how many of those hours are being spent on development and enhancements for better software? We spend more time identifying problems than solving them. We are stuck managing problems rather than improving, enhancing or innovating a better software. So, it is essential that project managers and tech leads monitor and enforce fundamental coding principles. One of them is better log file generation.
Some essential items that your log file must contain:
- Clearly define and practice what goes at which log level – INFO, WARNING, ERROR, DEBUG, etc.
- Execution context – the name of the function, timestamp, thread# other details as needed
- Use clear text to explain the action. It is not enough to print the function name. For instance, clearly mark the beginning of the process and end in all significant parts of code/functions
- Details of external calls like to Database or other programs – beginning of the call, end of the call, outgoing parameter, result parameters with precise details. For instance, clearly print your SQL statements with parameter values.
- Most of all, listen to support teams and others if they ask more just implement them without any debates. After all story of your code must be understood by all audience.
- Most of all, read it and improve until you hear nice story.
In the end, regardless of what language, technology platform or tools we use, software engineering principles are essential for building and supporting good software systems.