6 ms·

Ask HN: How often do you write comments in your code?

8 points by pvorb 9y ago

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.

mysterydip 9y ago
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 9y ago
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."
- meagher 9y ago
  Exactly! The best code I have ever read did complex things, but was easy to understand without much commenting at all.
- zer00eyz 9y ago
  > 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 9y ago
    There is a hitchhikers guide to the galaxy quality about that comment! Nice one.
SmellTheGlove 9y ago
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.
csorrell 9y ago
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.
psyc 9y ago
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.
pvorb 9y ago
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.

8 points by pvorb 9y ago

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.

mysterydip 9y ago

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 9y ago

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

meagher 9y ago
Exactly! The best code I have ever read did complex things, but was easy to understand without much commenting at all.
zer00eyz 9y ago
> 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 9y ago
  There is a hitchhikers guide to the galaxy quality about that comment! Nice one.

SmellTheGlove 9y ago

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.

csorrell 9y ago

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.

psyc 9y ago

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.

pvorb 9y ago

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.