How do you keep notes of your work as you code?
I find keeping mental models of the code I'm working on or reviewing to be a lot of cognitive work. So tend to jot things down either in a notebook or just put screenshots onto OneNote (I like the big endless canvas and ability to scribble notes). I feel like there is a more intuitive way for doing this. Any recommendations for tooling? How else do people do it?
Comments and documentation.
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.
Thanks for the reply. What do you think turns people off documentation? I hear about doc rot etc. Sounds like you've really seen the light. One of the issues I've had with docs is that they are quite non-visual, I tend to diagram quite a lot to get a sense of how things hang together.
Docs can include pictures, even rudimentary ones made in the simplest drawing tools.
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.
While I've tried all sorts of electronic aids, I've found the best was a full-sized Clairefontaine engineering-ruled spiral notebook. It's a scratchpad, it's graph paper, it's a place to tape stuff and it's a scribble-down place aside from a proper log. And I only have to remember now two things - we all have these neat phones that weren't there 5-10 years ago.
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.
Yeah nice! I have a gridded moleskine for the same purpose. Trouble is I tend to just write notes as I go and then not really refer back to them. Effectively an ephemeral scratch pad.
Since no one comments code anymore, I try to document the solution it in the commit message and JIRA ticket.
Interesting - what do you mean? Like the solution to a bug?
Yep, if its a hairy one..
At the very top of the file, I add:
/*
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.
Notion is pretty cool.
[dead]