At DjangoConUS 2023, I gave a lighting talk with this title. It was a lot of fun, and I'd suggest you try to give a lightning talk if you haven't before. It's a great way to try giving a talk at a conference without having to commit to a full 25 or 45 minute talk.
Here is a link to the talk, if you'd prefer to watch it.
With that intro out of the way, here are my strategies:
That's right, I'm saying you should write more documentation for your side project. Why? Context! If you need to stop working on your project, or if you are so deep in the authentication that you haven't touched the business logic in months (for example), you may forget a lot of the context around why your wrote the code the way you did, or what comes next.
But long form docs like these aren't the only kind of documentation you should write. Others include:
They document how you want your code to work. And how you don't want it to work (failure states you anticipate, bugs that you've found and written a regression test for, etc.). Reading tests can help provide context for the related code. They also mean that if you start writing code that touches a system you forgot about, it could catch an error in your new code. Write more tests! If you'd like to read more about my thoughts on testing, I wrote about that here.
Instead of keeping a plaintext TODO list, I like to use issues to lay out the work, prioritize, and sometimes have discussions with myself about how the work is progressing and what to do next. Simon Willison has a great blog post and talk with more depth about this strategy: The Perfect Commit. In terms of prioritization, I tend to use a Github project to shuffle the issues around which helps me think through longer term planning.
I find good comments to be incredibly helpful. Function, method, parameter, variable, etc. names should be self documenting. Comments aren't a substitute for those. But sometimes there is a hack or dense bit of code that needs explaining. Sometimes it's helpful to explain why a particular algorithm was chosen as in the example image. Sometimes this is (or should be) temporary, but sometimes I just can't figure out a way to do the thing that doesn't require at least a little explanation. I like to add comments so the next reader understands that context.
One way I find myself writing comments is that I write some (obviously brilliant) code, then come back to it after a few days | weeks | months and realize it isn't so obviously brilliant. When I remember why I did it that way, I put a comment so future me, or some other (un)lucky developer won't have to wonder.
But, Andrew, aren’t these great strategies for any project? Yes, but I'm highlighting them for side projects in this post because I think people tend to underestimate how helpful they can be in the long run.
Any strategies I missed, or any thoughts you have about any of these? Let me know! Email the site domain name [at] gmail.com, or reach out to me @email@example.com