DEV Community


Discussion on: What programming best practice do you disagree with?

pieteckhart profile image
Piet Eckhart

Code comments can be like deodorant for code smells. If you feel like writing a comment to clarify something, first try to change to structure of the code itself to make things more clear. Most of the time, simple (and safe) rename refacterings can be enough. After that try putting boolean expressions in properly named variables. If your happy about the naming you then can extract a method out of it so you can hide some of the implementation so the reader of your code doesn't have to mentally parse every tiny detail to get the big picture.

If you always so this your code will read like a story. Digging deeper you will find technical implementation but at the higher level it should be understandable by first time readers without having to peek at the lower levels. It takes a lot of practice and discipline tough.