This is of course a pun on the old phrase "If you don't tidy your room, you won't be getting any pocket money this week." in which privileges are withdrawn if tedious chores aren't completed.

It's not always fun to do the cleanup that follows in the wake of feature development.

Like the admonishment towards children, this has motivations beyond immediate gratification. If you don't tidy your codebase, it will begin to smell. This smell is your technical debt building up.

If you don't clean it up, it will become harder to do so in the future and it will also be more difficult to implement features.

Unlike most people's bedrooms however, you want to let everyone into your codebase so that other people can enjoy it and improve it.

Having an untidy codebase makes this difficult, because it's requires a significant incentive to work on an untidy codebase. Why would anyone else want to tidy your mess?

It's also worth noting that you from a month ago is a different person, so some projects can die from the original developer coming back to the mess they left and deciding it wasn't worth tidying.

So if you have a project that you have not touched in a while try to make some time to tidy up some of the mess.

It helps if you have left a TODO file to tell you what needs to be tidied rather than having to read through your codebase again to find the smells.

Tips for tidying C projects

It would be hypocritical for me to make these sweeping generalisations if I then did not follow through with it, so I am yet again going to use my linux-fsops project as the example.

  1. Tidy your source files into a directory of their own.

    Your project is more than just your code. There will be other artifacts you want to version control and at least in the short term one of the best places for this is your source code repository.

    So sorting your artifacts into a nice hierarchical tree helps especially when you need to keep track of things.

    It is also valuable in some programming environments. For example, Rust expects to have a src directory if you are using cargo, and for python projects it is handy to separate your code out into a library named after your project since this allows you to automate package generation.

  2. Split up large source files.

    Many helper functions would be usefully shared within your project and if you've defined your functions with low coupling then they may be useful independently, so splitting those functions out into separate source files is a step towards having a library that would be useful to others.

    Once every usefully divisible function has been split out, mark the rest as static, partly to ensure their defenitions don't leak, but also to signal intent that they aren't shared.

    Later steps may include turning it into an actual library by changing it to build as a shared object, having it install headers separately, and shipping the headers and shared object as separate packages, but until then it is still useful as a copy-library.

    Of special note is to have a missing.h for all the definiions that are not available from your system headers. It is conveneient to split it out this way since if you later decide to move to automake it has support for generating it automatically.

  3. Tidy your build-system.

    This is often the most-overlooked part of a project as it doesn't make the result itself better, but it makes it easier to make those improvements.

    In a Makefile it is necessary to ensure your make rules' dependencies and clean rules are correct.

  4. Don't worry about tidying everything at once.

    While it's better to have a completely tidied codebase, requiring that as a goal is likely to kill any enthusiasm in doing so.

    Incremental improvements are great. Every step is a step towards the goal. Perfect is the enemy of good. Other platitudes are available.

    Don't get hung up on the fact that your codebase still has stuff to tidy. So long as you've done something to improve it, you have not wasted your time. You can always do more later.

To to this end I have tidied up the build-system and split funcionality out in my linux-fsops project.

Now, if you're feeling particularly generous, you might think of a project you are involved in, and give the gift of tidy code this festive period!