Skip to content
Guides by jbrains

Summary

You have moved gradually from chaos to order, waiting for just enough chaos at each step to motivate you to take the next step. As it should be. You can balance chaos with order according to what you need right now. When you know the next step in organizing your code, you don’t need to agonize about when to take it—you’ll take it when you need to… or, more likely, just a little bit after you probably should have. I feel you.

The Steps

  1. Use inline expressions jammed into the main program… until that becomes hard to grasp.
  2. Extract expressions into functions alongside the main program… until that becomes hard to skim.
  3. Move everything into library files… until you’d rather be able to see the main program.
  4. Isolate function definitions from the main program… until you struggle with all those hard-to-skim pathnames.
  5. Isolate the library path from the library file names… until you struggle to keep straight which functions are in which libraries.
  6. Replace including libraries with importing modules.

You don’t score points for going to the next step until you start to feel the growing pains that tell you it’s time.

Have fun! Code in peace.

References

The jq tutorial. This shows an example that probably wants to progress past jamming inline expressions into the main program.

The jq manual. Everything you wanted to know about jq, but didn’t know you needed to ask.

The Code Whisperer. A blog about computer programming and software design.

blog.jbrains.ca. A blog about the software profession that looks at the wider life of the software professional.

jbrains.ca. More about me, including how to work with me.

Why I Wrote This

In 2023 I discovered Plain Text Accounting and began using hledger to manage the finances for a volunteer project that I lead. I noticed immediately that I was processing CSV and JSON files, which led me to combine jc, jq, and hledger for the project. In 2024 I adopted this toolset for both my personal finances and my corporate accounting. This was the beginning of my crash course in industrial-strength jq design and development. This guide is the result of that intense experience.