956 sats \ 3 replies \ @elvismercury 23 Nov 2023 \ parent \ on: Stacker Saloon
I grew to take writing good comments very seriously, and one time, after re-approaching code I had written a couple years earlier and forgotten everything about, I was so grateful for it, and resolved to always be maximally nice to my future self on this account, and then doubled down on the practice.
Some time later, I got a "fan letter" from a dev who had inherited a project that I had written. He talked about how much he enjoyed reading my comments. I then realized that in addition to helping your future self, commenting can be a literary form.
i used to write comments for everything like a true novice:
// do X x()
then I realized (or read an article, idk) that comments should explain why you're doing something, not what you're doing. i think my comments got a lot better after that.
but now i struggle with telling what will stay obvious and what will become a mystery as time goes on, lol
Some time later, I got a "fan letter" from a dev who had inherited a project that I had written. He talked about how much he enjoyed reading my comments. I then realized that in addition to helping your future self, commenting can be a literary form.
Wow, that's so nice from him!
I hope my colleagues at my previous company like my test suite of the project I wrote from the ground up over the span of almost 3 years.
I think I tested the shit out of this code, lol. Every bug needed a corresponding test case such that it never happens again.
Tests can be annoying when you refactor something but I hope they can look at all my tests to help them understand what the code is even supposed to do.
Tests are also part of a good documentation imo.
Documentation that never gets out of date.
and regarding
commenting can be a literary form.
that's a good way to look at it :) I try to write good PR descriptions now. It also helps myself with understanding what I did, haha
In general, good writing is an art in itself - but that's not a surprise :)
reply
then I realized (or read an article, idk) that comments should explain why you're doing something, not what you're doing. i think my comments got a lot better after that.
I think that's a pretty typical journey. Well, for those who arrive at the endpoint it's a typical journey. Many people never graduate from the 'do x' comment. One of my first bosses, the most talented guy I ever worked with, called this "commenting at the level of intent" which I always remembered.
In general, good writing is an art in itself - but that's not a surprise :)
Yup, you can write anything, no matter how boring, in a thoughtful, artful way. It's a superpower.
reply
deleted by author
reply