Ask HN: How often do you write comments in your code?
I recently had a discussion with a new colleague about how extensively code should be commented. Now, I'd like to hear the opinion of the HN community.
Also, this is the enterprise side of me, If I had to lean on a specific subject matter expert to understand a narrow piece of the domain before I could work through an issue, I try to be very specific about who that person was, but also what their specific domain expertise was - people leave, reorgs happen, but the goal is to have the reader understand where to go, provided that knowledge was transferred, independent of names and departments.
Example: I did a lot of data engineering in insurance earlier in my career, and sometimes it's really important for someone to understand non-obvious special conditions in code ("Generally, Product X had this provision, but we sold a policy form from 1998-2002 that had a slightly different provision, so you have to average the calc over a 3 month window instead of a specific effective date") - that's a generalized example of where I had to go pull hard copies of contracts to find that out, and I'd spare any future developer a week of research.
Also to break up a long structure into logical chunks, especially if the procedure is longer than a page.
When I start a function, I might write a couple comment lines about what it will do. Now I have a checklist to use as I write it, putting each bit of code under the line it's related to.
So to answer the question: I comment all the time, but notes, not essays. Hints here and there to make reading or remembering quicker.
You need to imagine how people will interact with your code and write just enough to help them understand the things that aren't already self evident.
I've found that the most clean, well maintained codebases I've worked with had VERY sparse comments, but the ones that did exist were critical to quickly understanding the "why."
I once found a comment that said something to the effect of:
// If you are here reading this it means things are very bad for what ever reason. I am sorry for the mess that follows but at the time it was the best possible solution. Your fucked!
Lets see who did this, oh look 3am checkin, by me, almost a year ago.
It was bad (all of it) and my comment was true to forum I was in a situation as described.
Whenever I feel the need to express myself in a comment I ask myself if I can simplify and clarify my code by extracting a method or variable with a descriptive name. In the end every method turns out to be doing only one thing or calling a sequence of other methods.
I only fall back to writing a comment when there's something that can't be expressed in the code itself, e.g. describing another obvious approach that didn't work out.
I also dislike comments that describe every detail about the code. Those tend to mismatch the actual behavior of the code as it gets older.