
Ask HN: How often do you write comments in your code? - pvorb
I recently had a discussion with a new colleague about how extensively code should be commented. Now, I&#x27;d like to hear the opinion of the HN community.
======
SmellTheGlove
At a minimum, I've always tried to comment when something took extra
research/effort for me to understand and implement, and definitely if I
learned something critical along the way. I'll try and point that out in the
comment. In addition, if I had to do something in a non-obvious, or non-clean
way, or if it would appear so to someone else, I comment that as well and try
to explain why it didn't/wouldn't work in seemingly more obvious approaches to
the problem.

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.

------
mysterydip
I write a comment any time I think there's something that won't be obvious if
I come back to it in a week.

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.

------
skylark
Good commenting requires empathy.

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

~~~
zer00eyz
> Good commenting requires empathy.

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.

~~~
bbcbasic
There is a hitchhikers guide to the galaxy quality about that comment! Nice
one.

------
csorrell
I mostly comment where I think there might be confusion about the reasoning
behind a particular piece of logic. I hate coming across code where I have to
wonder if I've found a logic error, or am just misunderstanding the desired
behavior.

------
pvorb
I try to avoid writing comments as much as possible.

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.

------
psyc
As little as possible. And, I consider every comment to be an implied TODO:
Simplify This. Caveat: I work alone, with no external deadlines, and my boss
(me) lets me refactor as much as I want.

