

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


======
soroso
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.

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

~~~
OafTobark
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
This is really helpful to understand. Thanks so much for sharing!

