I know it's not sexy, but adding lots of comments to the code will help to keep things organised, and will make your life next year sooo much better.
For higher-level concepts, usage examples, declarations of intent and expectation I cannot recommend "official" documentation more.
A lot of my career exists because I was forced by circumstance to write formal docs for my work. I refer to my own docs multiple times every day. Other people use my work because its documented.
And when I have to return to code, i find myself adding ever more comments to help me digest it. Personally I've never looked at code and thought "I can't use this, too many comments, too much documentation".
While I'm working I'm also writing (and rewriting) the docs.
For casual scribbles I use paper. I throw that away from time to time to reinforce how ethereal that is.
I have a motto now - if it's not documented, it doesn't exist. For me it matters 10x more than actual code, because it makes the code reusable, reliable and dependable.
Programmers don't like writing docs because it's work, not fun like having code. In some companies that's "someone else's job" which is terrible.
When youre young you think you'll remember every line of code you ever wrote. (Spoiler alert, over a 40 year career you'll write a LOT of code).
Code is just code. Docs make the code usable. I get paid when the code is used (well, purchased) so my incentives were clear. Plus it makes customer support a Lot easier.
There's no electronic search, which is a downer, but I date the entries so my goal is "know the date, know where to look to reestablish state". It works as I print pretty quickly and not too badly. Others might type, but then you either need two keyboards or two windows and you're tied to power or the net. I would think there's a real business opportunity here, but maybe the taking-note market isn't as large or as well-organized as one would like?
It's even pretty robust paper that could survive a bit of liquid. Coupled with a good pen it's a good writing environment.
/*
FILENAME: test.php
STATUS: Active
PURPOSE: this file is meant for testing.
NOTES: a lot of testing goes on this file, but it is never meant to be seen by the public.
*/
I need to get better at documenting my code, but I try to leave comments in block sections. I act as if one day, someone is going to buy my product and I am going to sell it to them, and they will take it over and want to see clean commented code. I know if I were the buyer and saw undocumented code, it wouldn't mean anything to me and I wouldn't want to buy it. If I saw nice code, I'm more enticed because I know what's going on in that code, can hire others to help, and no one has to guess, and we don't have to break anything or have any type of learning code.
Take Twitter for example... built on multiple levels of code, starting on Ruby On Rails, then evolved to Scala and Java with some Javascript in the mix. Re-writing code into another language is no easy task for any programmer, especially undocumented code. If the code, however, is documented, than instead of having to decipher what code is doing, it's all the more easier to read and re-write code into a new language if it is heavily documented. Hence... Twitter being bought by Elon Musk for $44 billion.
Although Elon Musk didn't technically buy Twitter because it has amazing well documented code, Twitter itself became a large corporation based on its own ability to somewhat organize, specifically its hashtags. Elon is not an active programmer and pays people to write code, but at some point in his life, he was a programmer who knew C and probably understands a lot of different code, as he oversees many projects involving code that performs different functions, specifically for Tesla.
So when writing code, always pretend that someone else is going to be looking over it and even better if you pretend they have no idea how to read code. With proper documentation, however, they won't need to understand how to read code.