Terse code plus lots of comments is better than so-called “self-documenting code”.

I don’t know, I feel like there can be a balance.

Use words and not characters for names.
Comment internals where the reasoning for a line of code might not be obvious.

Whenever someone tries to use single characters for generic names or variable names, I get twitchy.

@AmyShackles I do, in lambdas:
nodes.forEach(x => x.remove())

@kiki I only use single character names in lambdas if there’s only one thing going on. The second this turns into a multiline lambda, that fucker’s getting a real name. 😂

@AmyShackles yep, agree 🙌

When the scope is very small, short variable names are acceptable, even though I still prefer to spell it out.

Clever code is a pain to write and troubleshoot, so I avoid it. It is also just about the only time comments are helpful.

Another time is when you have to do something in a way you would rather not do it or there is some business reason for the choice and need to explain why to whoever comes after you. Or if there is some edge case or a TODO or noting similar code elsewhere that could probably rolled into this. Really, if it's actually going to be helpful, make it a comment.

What is not helpful is this:

#downcases string

def downcase_string(string)

string.downcase

end

Well-labeled code, and experience with the language (or documentation or both) is all really you need otherwise.

I’m also a fan of including Jira ticket numbers for todo tasks. If there’s not a ticket for a TODO item, it’s really just a TOFORGET

LOTS of comments is not ideal imo. Then you will not "see the forest for the trees, and people will miss critical comments in a tirade of insignificant comments.

But yes - I hate when people want to forbid comments entirely.

Using comments sparingly is the way to go for me.

Good code can be mostly self explanatory

Exceptions are

* Business decisions that make the code worse than normal

* Stuff that has to be done a certain way due to a 3rd party lib, like "This index starts at 1 because lib-x demands it"

* Describing expected return data of weird 3rd party services which cannot be looked up easily