> Writing comments explaining your motivation<p>This. Comments saying what you are doing is a code smell - not always wrong, but always worth a second look as to why the code wasn't clear by itself. Comments saying WHY code just did something are great because they convey the real info future me will need.<p>Despite the quoted statement, the article proceeds to give assertions/comments that don't fulfil that purpose. Assertions are fine, but (unless I misread) this is solving a different problem than good comments solve.