[jtheory]

My primary rule for commenting is to document anything likly to be unexpected or counter-intuitive to someone else on their first read of the code.

You don't always need to "document the why", because often it's obvious enough (with a well-named hierarchy of code, method names, etc.)... but it's essential to get a feel for times when someone else will see your code doing Y and think "ah, this would be easier if we just do X", and comment those carefully.

Related: read other code; get a sense for common programming idioms, and use the common approaches unless you have a really good reason not to.

You may be proud to have mastered a little-used feature in your language of choice that saves you a line of code here and there, but if the cost is that 80% of the people reading your code later are confused, you're not winning.

[ZoFreX]

> You may be proud to have mastered a little-used feature in your language of choice that saves you a line of code here and there, but if the cost is that 80% of the people reading your code later are confused, you're not winning.

What if it's a feature little-known within your team, but considered common or even idiomatic in the wider world?

[jtheory]

Then take the time to teach them about it, and why it's worth picking up.

Everyone wins in that scenario.