| 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. |