Exactly that! Everyone can See "what" is happening, the code is right there. But the code usually doesn't tell you "why" that is happening - good comments help understand the authors intent and give context, so you don't have to guess.

Good comments should explain the things that are not obvious.

Good comments more than once prevented me from accidentially undoing a fix.

[–] [email protected] 2 points 1 year ago* (last edited 1 year ago)

Yup my comments are generally along the lines of:

I could have done this X way, but it ran slower
I was running out of time so this it’s mostly copied from (stack overflow url)
refactor when time allows

This is a side effect of doing lots of tiny websites , microcontroller code and mini web apps for under budgeted marketing projects with constantly changing designs and requirements that don’t need to last too long.

[–] [email protected] 4 points 1 year ago (2 children)

comments are for explaining why you did things a certain way

A while back I spent more than a year modifying my company's iOS apps so that they would work properly with VoiceOver (Apple's screen reader technology for blind people) and be compliant with FCC regulations for accessibility (and save us from $1 million per month fines lol). The thing about VoiceOver is that it's bizarrely buggy (or was - maybe they've fixed the problems since then) and even when I didn't run into VO bugs, the way that developers tended to architect these apps often made getting them to behave properly with VoiceOver extremely difficult.

I often had to resort to very strange hacks in order to get things to work, and I would always leave comments explaining what I had done for this. My manager was one of the new breed who not only thought comments were unnecessary in ALL cases but also thought comments were a "code smell" and indicative of professional incompetence on the part of anyone who used them. Whenever he reviewed my code, he would leave in the hacks (after trying and failing to fix the problems without them) but remove my comments. This resulted in many cases later of developers contacting me to ask me why some bizarre bit of code was in the app in the first place. I always referred them to my manager with an NMP (Not My Problem any more).

[–] [email protected] 3 points 1 year ago

I think most people fail to understand what code smell really is. They think code smell means bad code. A code smell is actually an indication that something else might be bad with the code. The code smell itself might not be bad.

So when a code smell appears, it means you should identify the reason it exists and potentially fix it. In this case the bad code is a buggy external library, which is difficult for you to fix. Therefore, leaving the “code smell” is the best course of action.

Your manager was in the wrong and you were right to write comments.

[–] [email protected] 2 points 1 year ago (1 children)

This resulted in many cases later of developers contacting me to ask me why some bizarre bit of code was in the app in the first place. I always referred them to my manager with an NMP (Not My Problem any more).

I hope this isn't a real story. It would have taken you just as long to refer them to the commits with your comments still in, and run a git blame to show your manager took them out. Instead you just make yourself look unhelpful and incompetent.

[–] [email protected] 5 points 1 year ago

Bold of you to assume they were using source control under that manager...