DEV Community

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

Collapse
 
giangvincent profile image
giang vincent

Write comments in every function, and at the beginning of every class. Sometimes the projects will go really complicated, then you must roll over again every class you write just to look what it does.
What you need to do is create a structure and a walk through tutorial when things out of hands.

Collapse
 
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.