Art of Clean Code - Logging

 "In some ways, programming is like painting. You start with a blank canvas and certain basic raw materials. You use a combination of science, art, and craft to determine what to do with them." - Andrew Hunt

My first lesson for importance of logging was in 2001-02, from my manager and coach Puneet Agarwal. We were building a framework for Data Bound Swing Components which can be used to design any application using a custom Net Beans kind of IDE, to enable rapid application development.

Design was to extend Swing Components, attach metadata for data source/s in context and pass it across component hierarchy using component life cycle events like add/removeNotify, and extend paint/print functions to render the components using data. This seems like a simple design flow, but had complex implementation due to hierarchical nature of UI elements. Data needs to be passed (and cleaned too) from parent to children and vice versa. Which means, any break in this recursive flow or any small miss (ex: even mishandling of data loading in repeated rendering events trigger by Swing) could cause issue in data loading, in rendering, memory management, and on focus kind of user facing features also.

The only savior to debug in such complex recursive programming environment was 'art of logging'. This is when my manager taught me the importance of logs, including right level of logs with right level of information and easy to understand format. I still remember that lesson and follow it that,

Logging is an Art

Fast forward today, we have much advanced features in IDE, ex: breakpoints, debug mode etc. These are making debugging much easier with live runtime data and control on start, restart and stop of events. Having said that, when there is issue in server or distributed environments, logs are very useful to understand the issue in one go by looking at logged data. Even in local dev environment also, it is much easier to see the whole system state by reading the properly crafted logs in one go.

Hence an effective logging is very important for clean code, a code which can be maintained easily for long, a code which can run in production without causing distress in nights for developers / ops / users and is easy to debug and fix quickly if there is any issue.

Let's talk about few of the important basics to make logging effective, and hence to write a clean effective code.

Have a common understanding of 'Format of Logs'

Yes, it is important. Refer to previous blog here about clean code, where we discussed about having standard formatting for codebase in a team, as it makes reading code easy. Same principle applies to logs also. If there are different kinds of log formatting, and patterns, it takes time to understand, and makes sense of it.

We should be able to read logs like a Story . A story narrating the state of system in simple words

Art of Clean Code

 If someone ask me who is my Guru for Java, I would say 'Sun Microsystem' and 'Apache Foundation'.

I am from a generation, where most of the programming learning was by reading Java source code. Internet was not a big store of many rich blogs or forums, and hence reading through code was the best resource. Moreover, kind of components we built, were not possible without understanding the behavior of system we are extending. Hence reading through code was almost mandatory for building right extension, and the products.

One notable thing, I still remember and admire about Java and Apache kind of products source code is, clarity of code constructs and rich documentation, code which speaks its intention very clearly. That made the code reading experience enjoyable and easy like a story book. I remember reading tons of code of Swing, Concurrent library, Collections and Apache Axis etc like a novel. Much of the credit of reading such large codebase was to that effective coding and documentation style, which developers followed to write such code.

Fast forward today, we are in era where doing more by writing lesser code is sought after style. With availability of functional language, many abstract language constructs and lambada expression kind of support, it makes all the sense and makes code less bulky too.

Yesterday or today, then or now, basic principles of writing clean code are same and equally required. Ultimately it is all about art of writing readable code, clean code, a code which speaks of its intention clearly, where it is hard for bugs to hide, a code which can tell about any dysfunction loudly.

What is clean code:

Any fool can write code that a computer can understand. Good programmers write code that humans can understand - Martin Fowler

  • A code which can be read easily by anyone and everyone other than its original author.
  • A code which speaks of its intention clearly, either with write naming convention or with documentation as relevant
  • A code where it is hard for bugs to hide
  • A code which can tell about any dysfunction in system loudly itself
  • Let us talk in brief about some of key enabler principles for clean code.

Meaningful Names - Names which reveals intention

If I need to choose one most important thing for clean code, I will pick this. That is its importance for code readability and maintainability.

Picking right name, which can reveal its intention of existence is very important. It takes time to pick right name, however, that effort and time are worth it as it could save hours of efforts later to understand the code or any issue.