Tools: Dear Future Me: How to Write Code You Won't Hate in 6 Months

The "I'll Remember This" Lie ## 1. The "Why," Not the "What" ## 2. The DECISIONS.md File (ADRs Lite) ## 3. The "Scratchpad" Journal ## 4. The README is your Deployment Manual ## Summary: Documentation is Self-Care We tell ourselves the same lie every day. "I don't need to write down why I used this specific regex. It’s obvious. I built it. I am the god of this repo." Then, three months pass. You come back to the project to fix a bug. You stare at that regex. You have absolutely no idea what it does, why it's there, or what will break if you touch it. Welcome to Context Bankruptcy. When you are a solo developer (the "One Person Framework"), you assume documentation is for teams. You assume it's for handing off knowledge to others. This is wrong. Documentation is time travel. It is a message from Past You (who was smart and in the zone) to Future You (who is tired, busy, and has forgotten everything). Here are the 4 low-effort documentation strategies that will save your sanity. Junior developers comment on what the code is doing. Senior developers comment on why the code looks weird. The code itself tells you what is happening (user.save!). You don't need a comment for that. You need comments for the invisible constraints. Strategy: Only comment on things that look like mistakes or hacks. If you had to Google a weird error to fix a line, paste the StackOverflow URL in a comment right above that line. In big companies, they use "Architecture Decision Records" (ADRs). They are formal documents. You don't need that. You just need a markdown file in your root folder called decisions.md. When you make a big tech choice, write 3 sentences. Why this matters: In a year, you will read a blog post saying "Sidekiq is faster!" and you will feel the urge to refactor. You check this file, realize your constraints haven't changed, and you save yourself a week of wasted work. Context switching destroys solo devs. If you work on your app on Saturday, and then don't touch it until next Saturday, you spend the first 2 hours just figuring out where you left off. Create a file called SCRATCHPAD.md (and add it to .gitignore if you want, though I commit mine). At the end of every coding session, write a "Dump": "I got the billing form working, but the webhook is failing with a 400 error. I suspect it's the CSRF token. The next step is to look at the StripeController." When you sit down next week, you don't have to load the entire architecture into your brain. You just read the last line and start coding. The scariest moment for a solo dev is deploying a hotfix 6 months after launch. "Wait, do I run fly deploy or kamal deploy? Do I need to migrate the DB manually?" Your README.md should not be a description of the project. It should be an Instruction Manual for Emergencies. When you work alone, you don't have a senior engineer to ask for help. You are the senior engineer. If you don't write things down, every time you open your editor, you are forced to re-solve problems you already solved months ago. That is the definition of burnout. Be kind to Future You. Write a note. What is the one thing you always forget about your own code? Tell me in the comments! 👇 Templates let you quickly answer FAQs or store snippets for re-use. Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment's permalink. Hide child comments as well For further actions, you may consider blocking this person and/or reporting abuse COMMAND_BLOCK: # Sets timeout to 5000 config.timeout = 5000 Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: # Sets timeout to 5000 config.timeout = 5000 COMMAND_BLOCK: # Sets timeout to 5000 config.timeout = 5000 COMMAND_BLOCK: # We set this to 5000 because the Stripe API webhook # occasionally hangs for 4s during nightly maintenance. # Do not lower this without checking their status page. config.timeout = 5000 Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: # We set this to 5000 because the Stripe API webhook # occasionally hangs for 4s during nightly maintenance. # Do not lower this without checking their status page. config.timeout = 5000 COMMAND_BLOCK: # We set this to 5000 because the Stripe API webhook # occasionally hangs for 4s during nightly maintenance. # Do not lower this without checking their status page. config.timeout = 5000 - Date: 2026-02-03 - Decision: Switched from Sidekiq to Solid Queue. - Why: I didn't want to pay $15/mo for a Redis instance on Render. Solid Queue handles my volume (50 jobs/day) fine. - How to start the app locally: (bin/dev) - How to deploy: (kamal deploy) - How to access the production console: (ssh user@ip -t 'app console') - Where the secrets are: (e.g., "See 1Password vault 'Project X'")