5 ms·

Ask HN: How important is code commenting in your org? What is your org?

mtmail 11y ago
Counter question: Is there any professional organization where code commenting is not important? Even if I work alone I write comments because I can't recognize my own code a year later.
- a_lifters_life 11y ago
  Well, a lot of people / orgs say its important, but dont do it..
- OafTobark 11y ago
  I won't name the now defunct startup (well funded and founded by a proven founder) but they hired an engineer who was basically the CTO (although one of the other co-founder officially held the title). I was told that this guy (the CTO-engineer was one of the best engineers and in a convo with him, he basically told me he doesn't believe in commenting and that you should write code that is self explanatory. I basically lost respect for him on the spot no matter how talented he was by everyone else's view. For what it's worth this was a team of over 15 people and about half the team were engineers and everyone thought this guy was insanely good (although I have no clue if any of that is true or not)
  - a_lifters_life 11y ago
    This is really helpful to understand. Thanks so much for sharing!
- Jeremy1026 11y ago
  Where I am doesn't put any stock into comments. Our commit messages are even worse.
  - a_lifters_life 11y ago
    Why do you think that is? Can you give me a bit more info into your org?
soroso 11y ago
Cannot say about my current company, but the last one (a real estate listing agency in South America). It was very important, but there was always a huge debate of what was important to comment. One developer thought that adding docblocks was just enough. The other thought about commenting the why of code blocks etc. So your question may sound like "How important it is to live within your own means". Everyone will agree, at some level, the living within means is important - but people will diverge on whether you just give up your goals or aiming for them anyway. Comments as much as code are meant for human eyes. The main difference are that comments are not executed, therefore they are less likely to be updated when the reason for a piece of code changes as well. Programmers update code until it compiles and passes tests, but it doesn't follow they update comments accordingly. Nothing is more misleading than an outdated comment. Also, you might find those who will say that if the code is self-evident, then it does not need commenting. Which is theoretically true, but usually people miscalculate the ability of later read to extract context of uncommented code.

Counter question: Is there any professional organization where code commenting is not important? Even if I work alone I write comments because I can't recognize my own code a year later.

a_lifters_life 11y ago
Well, a lot of people / orgs say its important, but dont do it..
OafTobark 11y ago
I won't name the now defunct startup (well funded and founded by a proven founder) but they hired an engineer who was basically the CTO (although one of the other co-founder officially held the title). I was told that this guy (the CTO-engineer was one of the best engineers and in a convo with him, he basically told me he doesn't believe in commenting and that you should write code that is self explanatory. I basically lost respect for him on the spot no matter how talented he was by everyone else's view. For what it's worth this was a team of over 15 people and about half the team were engineers and everyone thought this guy was insanely good (although I have no clue if any of that is true or not)
- a_lifters_life 11y ago
  This is really helpful to understand. Thanks so much for sharing!
Jeremy1026 11y ago
Where I am doesn't put any stock into comments. Our commit messages are even worse.
- a_lifters_life 11y ago
  Why do you think that is? Can you give me a bit more info into your org?

soroso 11y ago

Cannot say about my current company, but the last one (a real estate listing agency in South America). It was very important, but there was always a huge debate of what was important to comment. One developer thought that adding docblocks was just enough. The other thought about commenting the why of code blocks etc. So your question may sound like "How important it is to live within your own means". Everyone will agree, at some level, the living within means is important - but people will diverge on whether you just give up your goals or aiming for them anyway. Comments as much as code are meant for human eyes. The main difference are that comments are not executed, therefore they are less likely to be updated when the reason for a piece of code changes as well. Programmers update code until it compiles and passes tests, but it doesn't follow they update comments accordingly. Nothing is more misleading than an outdated comment. Also, you might find those who will say that if the code is self-evident, then it does not need commenting. Which is theoretically true, but usually people miscalculate the ability of later read to extract context of uncommented code.