wb5/posts/prod.md

how to not abandon side projects

2023-05-15

I don't personally have any position of authority to back up the following tips. However I can attest that at least for me, they were useful.

the to-do list

I found that while writing larger personal projects, motivation was one of the issues that plagued me the most. Oftentimes, I'd take a break from the project for a week or so, then lose the will to continue.

I would find that either I had no idea what to do next, or that tasks were too daunting to accomplish. And after that, I would let the project collect dust in an abandoned repo.

One day, while browsing Telodondria's code, I found a curious TODO file.

It looked like this:

Telodendria To-Do List
======================

Key:

[ ] Not Started
[x] Done
[~] In Progress
[!] Won't Fix

Milestone: v0.3.0
-----------------

[~] Stream API
    [x] Implementation
    [x] Convert all code that deals with I/O
    [!] Multi-output (proof of concept)
    [!] Memory streams (proof of concept)
    [ ] TLS

I did the obvious thing to do in this situation, and stole the idea to use it in my own project. As it turns out, having a to-do list fixed both problems described above for me.

When creating one, you're essentially assigning future you tasks to do. The great thing about always having tasks laid out in front of you is that you never have to figure what to do next: you already did that job. Instead of having to plan out everything, you can focus on actually implementing things.

The to-do list also forces you to divide your project into manageable pieces. For me, my top-level tasks were components of a system like Implement authentication. Every time I'd get to implementing one of these components, I'd then divide it into smaller, more concrete pieces, like Implement /users/<id> PATCH. Usually, these small tasks were items I could reasonably complete in an evening. So basically, there never was this feeling of being overwhelmed, as I always knew that I'd make decent progress on the project in one session.

docstrings

In the spirit of planning things out, I also wrote docstrings before writing important classes and functions. Most importantly, it's good to have a solid definition of what you're about to implement. It just so happens the Python docstring is a good way to do that: you have parameters, a description, and a return value in a function docstring. With Neovim, I'd have the docstring open in a split, and actually code the function in another. This way, there's no confusion about what you're supposed to write.

Planning everything out ahead of time is really useful for me. When I come back to work-in-progress code from a week back, I'm not in the same state of mind. Often, I'll have forgotten what I was trying to do in a given place: that's why leaving good comments and docstrings is helpful.

Of course, this "standard" specified by the docstring isn't formal or inflexible. It's not a real specification; it's a short-term plan. Sometimes, midway during implementation, I'll realize that the docstring describes a function that can't work. However, that's a good thing: if I didn't have the plan, I might not have realized my code wasn't coherent.

conclusion

To be honest, using a divide-and-conquer strategy to complete projects has been working for me. Thanks to planning tasks out in a high-level to-do list, and more fine-grained docstrings, I have been avoiding lack of motivation, and forgetting what I'm supposed to be doing.