You may be talking about something else.. I'm a beginner (first job), but I tend to make use of comments and commit messages (this may be due to the fact I buy pens and notebooks in bulk and have a tendency to take notes).
Comments:
I write them so I can just do a git grep and have a lot of information. Read: they tend to follow a certain format.
TODOS are for code I write that I intend to add. Others will probably read them and might do them, or tell me not to do them because of a reason I wasn't aware of.
# TODO: Refactor this so it doesn't make that many copies.
# Something along these lines:
# def foo(arg1, arg2, *, bar=None):
# ...
# This way we can do x, y, z. Profiling shows spam
# spends most of it time doing x instead of y.
# Investigate why. Maybe do it à la PEP 666.
However, I sometimes open a ticket, assign it to myself, add a proposed implementation off the top of my head in the ticket body, then just reference the ticket in the TODO not to clutter the code (the information is captured nonetheless).
I also have files "musing" and "refactoring": the first where I toy with things that, somehow, always manage to save the day when I need them. Custom data structures, utilities, tools to make things easier. I suck so I try really hard to make my code really easy to use and write code to be able to be as lazy as possible (and learn a few things doing it)
'refactoring' is when I don't want to mess with someone's code but I see a way of doing something I'm not certain is better and that portion is not a priority. I'll reference the file and the function and make it better. It almost always is because I have the luxury of perspective the person that implemented it first didn't have, whether that person is me in the past, or another human.
# QUESTION: Why does foo instantiate CoolStuff with arg
# when bar does it too in yo.py
A question is useful in many cases: When the information is with someone else but I don't want to unplug from the code; I just capture that in a question and continue working on the code. I do a git grep periodically to see if my questions are answered (I might have gained more insights into a subject, or talked with another person, or just got some sleep. The questioning not being lost is what's important because I think code is just answering questions).
You can also append the person's name or something.
If I do something that's not obvious, I add comments on what I was trying to fix, how I fixed it, and why that way instead of another. This way a reader might get their answer. I add "# NOTE:" for emphasis.
If I do a temporary thing, I also use warnings so I can run and generate errors and prefix functions with _throwaway (this way I can git grep them).
Commit messages:
They tend to include what was changed and why (which issue/wart it fixed and why it was a wart/issue because is it really a bug or was it intended? and how it was fixed) plus the next steps I'm planning to do after that commit.
Goes like this:
X feature is working now. Problem was that foo did xyz
but didn't commit to the db and condition Y wasn't met
yet. Change affects foo method in waw.py.
Next steps: Implement Z feature and refactor W so it uses
memoryview instead of making all those copies in z.py.
When I'm the only one working on the code, I go insane with comments, etc. When the code involves other people, I tend to have a branch where I have a lot of stuff, but will push a more mentally sane branch for others to use.
This allows me to:
- Have a set of questions I can ask and get answers to. If I'm talking with someone, I do a git grep and see if their name doesn't come up and ask them a question I wanted to ask them when I was doing x, y, or z.
- Know what the next steps are.
- Have context about my own stuff.
- Brain crumbs so there's always something to work on.
- Hopefully be someone they can have unprotected code with.
