Project TODOs: Track, Share, and Build Better Software

One of the challenges of working on a time-sensitive project is balancing getting something working while also keeping track of the various document, tasks, issues, and general project TODOs.

I don’t know what this looks like for you. But for me. project TODOs usually fall into one of two groups:

  1. I need to go back and document a file, class, property (or properties), functions, or module.
  2. There are places that I know need to be refactored. Perhaps a function needs to be split into two methods. Perhaps I need to rework an algorithm. Whatever the case, there’s something that needs to be done before I’m happy with it being final.

And when that’s the case, it’s easy to forget to come back to these areas in the code and rework them as you see fit.

This is where the idea of project TODOs come in, but I even think we can take it a bit further.

Why Project TODOs Matter

At the most basic level, you can easily do a “find” or a “find all” for TODO statements throughout all of your code, but that’s almost archaic at this point, isn’t it?

Most modern editors (and certainly IDEs) have packages or features that allow us to track project TODOs so that we can easily refer to them as we’re working.

Project TODOs: An Example
An example of a simple Project TODO file.

It’s great, it’s convenient, and all of that jazz, but one of the things I’ve found useful when working with clients is to also let them know what things need to be done before jumping into the next milestone.

It Comes Back to Code Quality

If you’re working for a large company or even a mid-size agency, this may not be an issue. But if you’re a small team working on a time-sensitive project, I think that one of the first priorities is to make sure you’re getting functional deliverables into the hands of your clients.

I’m not saying to turn over something half-baked. The feature should always match the requirement to its fullest extent. But if another milestone comes up, or something undergoes a new phase of planning, I’ve found it to be helpful to share what things need to be cleaned up a bit by sharing what project TODOs I have left throughout the code.

And the reason this is important is because people will claim they care about code quality, but often times they just care if it works. But if they have some type of visual representation of things that are outstanding that directly affect the code quality, then the conversation changes.

That’s when you have the ability to go back, clean up the documentation, tighten it up, refactor certain areas, and so on.

Here’s the thing, though:

This is not an excuse for writing poor code the first time around. This is not an excuse for delaying a project. This is not an excuse for doing something less than the best you can under necessary constraints the first time around.

Instead, this is all built on the idea that you’ve done your best with the time allotted under the constraints given. But if the project is going to scale and to be amenable to change now and later, it needs to have these things adjusted.

So what are we to do?

Project TODOs To File

I’ve begun including a TODO.md file with my projects. Most of the packages that I’ve seen make it possible to export them in HTML format, markdown format, or even just in plain text.

The file type doesn’t matter.

Project TODO: Markdown file in a GitHub Repository.
A project TODO.md file a GitHub repository visually, yet silently glaring at us and reminding what needs attention.

But if you’re able, at a certain point, to take a snapshot of the TODOs that exist throughout your codebase after a major milestone has been completed, share it with your client or stakeholders, talk to them about why it’s important, and show them what needs to be done, you’re more than likely going to be able to refactor them.

Personally Speaking

As an example, I’ll share that I do this but I do it only under the condition that I’m able to take a day or so (no more than a business week in extreme cases) to tighten things up, and then get back to work.

Secondly, I try to make sure that I’m able to work on this while the requirements, design, or some other aspect of a project needs to be done from another part of a team so we’re working in tandem on two different parts of the project.

Don’t Buy Time; Instill Quality

Again, this is not about laziness or trying to buy time. It’s a way to be pragmatic. So next time you’re looking at finding a way to ship something to your customer while balancing a level of “I need to go back and do this at some point,” just leave a note in the code, generate a file, and have the conversation later.

My guess is that it will be fine permitting you can fit that work in while the rest of the team is working on something else at the same time.

Even if not, at least you have a visual of outstanding things that need to be done at some point. And anyone who truly cares about code quality can’t ignore a file that lists out all of the things that still need to be tightened up to have a software project up to a high standard.

2 Replies to “Project TODOs: Track, Share, and Build Better Software”

  1. Since you mentioned modern editors / IDEs, is there any reason you choose to put TODOs in one file, as opposed to inlining them where relevant for context?

    Maybe I am just spoiled but PHPStorm already shows all todos in your code organized into folder style views so you can browse & filter TODOs based on context.

    A decent build routine could even collate them from the entire project into one TODO.md file and add file/line info with it for an index.

    1. Maybe I am just spoiled but PHPStorm already shows all todos in your code organized into folder style views so you can browse & filter TODOs based on context.

      Most IDEs do this (and editors have packages to do this, too). I don’t think was I clear in the post so that’s on me. My bad!

      A decent build routine could even collate them from the entire project into one TODO.md file and add file/line info with it for an index

      That’s exactly what I do and drop ’em in the repository.

      The point of the post is simply to urge others to do the same that programmers do for themselves to help stakeholders understand what’s under the covers that need attention. It’s more for them, less for us.

      I hope that clarifies it (but if not, let me know — always happy to chat more :).

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.