DEV Community

Discussion on: A short comment on comments in the code

Collapse
 
mylopeda profile image
Jakob Carlsson

After reading A Philosophy of Software Design (amazon.com/Philosophy-Software-Des...) my take on this is that comments that describe WHAT the code is doing on the same abstraction level as the code should not be written. If the comment is describing WHAT the code is doing on a higher abstraction level it might be something good to write, might be, it depends on the situation and how the comment is written (so that it really is on a higher abstraction level).

Comments that describe WHY the code is doing something or doing something in a specific way should be written when needed (and also sometimes when not needed) to tell the other developers (and future you) why a specific way was chosen. A good example from my personal work life is when I wrote a function with about 20 lines of code doing a thing that could be done using a one-liner with a regular expression, the reason for me to chose the 20 line method was that it was much much quicker and this specific method would be running many times so how quick it was running was more important than if if could be written using fewer lines of code or not.