I’m constantly amazed at how bad programmers are when it comes to designing good logging and reporting utilities. Hopefully your tool support input from stdin and allows for writing logs or interactions to stdout. If you haven’t gotten that right, I’m not sure what you are doing.
But when it comes to report- and logging-formats many programmers go astray.
All logs and reports should be generated in a structured unambiguous format that is easily parsed. If you want human readable, write an adapter that converts from the structured format to human readably.
$> mytool | mytooltohumanreadableconverter
Why bother with that, why not just generate output the way you want it right away? Here is why! You will most likely find other uses than just reading it off the console. If you have a structured format, it becomes easy to write adapters that can convert to pdf, doc, or other not only human readable but also human usable formats.
To use an example: output from tools such as a unit-test framework.
You run the tool in console and the output looks great. It is easy to read as a human and everything is fine. What if you want to run your test on your CI-build-server, such as Jenkins? You want to aggregate hundreds of test runs, collect statistics over time? Parsing the human readable output can be a nightmare. What about running the tests from within an IDE –such as Eclipse?
With a structured format, it is easy to write an adapter that converts the output to single-line, structured text that is easy to write an error-parser using the generic one provided in Eclipse. With not much effort you can see the errors highlighted in the source code –with correct meta-data about the error. If the human readable output contains line-breaks, not uncommon to make an entry easy to read for humans, it becomes very difficult for the Eclipse generic error parser to find all the information in a cohesive way.
- Structured output also allows for the writing of additional tools for log and report analysis and visualization.
- It becomes easy to parse the output and write it to a database.
The options become endless. But if you go the route of human readable, it becomes close to impossible to do anything else than just human readable –in that specific setting.
The same can be said about program output to standard out. Imaging the output to be structured, than parsed and converted to human readable. All of a sudden it becomes very simple to write interactive programs that can talk to other programs using the stdin – stdout interface. You can write an adapter and connect it to a socket. All of a sudden you have a program that works remote, and across platforms.
Using stdin and stdout to allow piping information is not enough. Structured output and input makes your program more versatile and makes it much easier to fit into a full tool-chain or other grander settings.