228 sats \ 2 replies \ @ek 23 Nov 2023 \ parent \ on: Stacker Saloon
i used to write comments for everything like a true novice:
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
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
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 :)
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