AEvery time :D

yes, please comment your code, and don't let anybody tell you otherwise.

@ostream If the code is good enough, the comments are redundant. The cargo cult programmer sees that removing comments can make already good code even better, and concludes that removing comments improves code quality, which he then applies to his convoluted garbage code which desperately needs comments.

Agree that comments are a code smell. Sometimes they might be valuable though, personally I’ve found that I can improve readability with better variable names or refactor parts. That’s until I encounter the inevitable, a section which makes something weird, an optimisation, calling an external lib, or whatever.

Also found that people don’t update comments when they are touching the code which would require an update, so the comments start lying at some point.

@lorentz @ostream
dafuq are you guys even talking about?
Commenting code is something you should do automatically. I doesn't make a difference to the Computer if you comment or not. However code is written by people. And people are ultimately the ones who need to understand, wtf you're writing. Just become a decent human being and comment your stuff for crying out loud.

@thebiochemic More text isn't automatically good. Comments are useful if they are true and not expressible in machine-verified logic. Ensuring these takes effort. Yes, comments generally improve code, but not all comments improve code and sometimes even the best possible comment isn't a very good change compared to much easier alternatives, so they have to be remembered as yet another possible improvement alongside such others as making invalid state unrepresentable or localizing behaviour, and not magic sauce to make bad code good.

In principle, all items that hide something should have a comment. Every time the semantic meaning is different from the concrete code, a comment is justified.

Full disclosure, I don't comment internal behaviour enough, instead I split out modules, carefully inspect and overhaul the interface, test and document it. I don't like to document internal behaviour because it's prone to minor changes and I hate combing comments for outdated statements.

See my comment on: https://devrant.com/rants/9815817/...

@ostream that is also too extreme and bullshit.

Code can express function and sometimes intention but not reason.

I added a comment today because we check for financial field changes to trigger some shit. However there is one field that is not in the list that triggers it. Looks like a mistake, however the code is clear and correct. I've added why the business requires this particular field to be excluded from the trigger.

Edit: perhaps it's part of the "hack or something"

Comments on public APIs should be extensive, useful and well written. Comments on internal code - few and far between, if at all.

@ostream it's not stupid. There is a very valid technical reason for it (authoritative source that is already used to trigger changes in this case) your code interacts with the real world that is its purpose.
The scope of the code does not always reveal that. So if you would add that field because there is no comment when touching the code and think it's missing you are actually failing as an engineer. But hey an engineer cares about the problem domain and educates managers by pushing back on stupidity.

It's also fine to be a programmer. Just implement something that somebody else designed and you don't care as long as you get to write code.

@ostream the problem, and that is very common with developers, is that the judgement of what needs to be commented is often times on the more conservative side. And when you need to know _exactly_, what you did 6 Months ago, then youll be fucked.

However i agree, that you shouldn't comment every fart. I like to see an interface documentation though, and there is no reason to not do it.