28 June 2017

Comments are not welcome

Comments are not welcome.

Think about this, a programmer, who knows their language and environment, shouldn't really need your commentary on the code. You code should be clear and expressive. When it isn't clear or expressive, your test suite should explain it. There should really be no need for your comments.

If there is a need for comments it should be to express something that is so phenomenally complicated that there just wasn't an easier way. Or may an expression of non-intuitive behavior in the code as expressed by business requirements. That said, the tests contain the answer of what is true.

Naming things, good method names, good class names, good variable and argument names, is where the clarity of what the code does come from. 

There are cases when you have some code you aren't sure about. Code you aren't 100% sure you can delete. SCM is your tool here. Delete it, get rid of the noise. If you need to restore the code you deleted, use your source control tools to bring it back from the dead. Don't ever check in code that is dead or commented out. It just creates confusion.

Thanks to Mike Gantz for reminding me of this.