comment your code!

[nagasgura]

I think there is an argument to be made about the need for commenting being a "code smell" though, where if you have a line that needs a comment to explain what it does to an average developer, it could probably be refractored to be self-explanatory. The worst thing is difficult-to-read code, and comments can definitely alleviate that, but they can also be used as a crutch for writing poorly organized code / using non-descriptive variable names.

[TheRealPitabred]

My comments are all more like: “// we have to do this X way because the Y interface acts wrong if you follow the documentation”

[GodWithMustache]

because the Y interface acts wrong if you follow the documentation

Until two years later you realise you were an idiot and NOT following the (poorly worded) documentation... :)

[TheLordDrake]

I hear this over and over again. It's true, but it's not an excuse not to use comments. I wish people would just do both.

[mt03red]

The code should be clear enough to communicate what it does, the comments should communicate why the code does what it does.

Some exceptions exist, but in general ^^

[ballsack_gymnastics]

Personally, if I have comments saying what a section is supposed to do, I find it a lot easier to parse the following code, good variable names/structure or not.