I personally encourage my colleagues to write as few as possible comments. I call such comments 'excuses'.
When I read a function or method signature it should be immediately clear to me what that function or method does, how it should be use and what's its purpose. I shouldn't have to know any details about the implementation to use it. Virtually any function can be designed with such clarity in mind.
A similar approach can be attempted for implementation. Any code contained in a function 'worthy' of an 'excuse' can be refactored into another function with clear intent and purpose. I don't care that it will be called in a single place if it brings clarity.
Of course, I allow 'excuses' if the offending piece of code is not the developer's fault, like with strange business logic or partial solutions based on incomplete information. My point is that comments shouldn't be used liberally. Code can and should be written with clarity in mind, especially if you share the codebase with lots of other devs.
I write tutorials on my blog at www.lankydan.dev . During the day, I am a Platform Engineer at r3 where I work on Corda, an Open Source DLT/Blockchain Platform.
Agreed. Not much is more annoying than a function which leaves you more confused after reading its name or does something different to what it says it should!
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
I personally encourage my colleagues to write as few as possible comments. I call such comments 'excuses'.
When I read a function or method signature it should be immediately clear to me what that function or method does, how it should be use and what's its purpose. I shouldn't have to know any details about the implementation to use it. Virtually any function can be designed with such clarity in mind.
A similar approach can be attempted for implementation. Any code contained in a function 'worthy' of an 'excuse' can be refactored into another function with clear intent and purpose. I don't care that it will be called in a single place if it brings clarity.
Of course, I allow 'excuses' if the offending piece of code is not the developer's fault, like with strange business logic or partial solutions based on incomplete information. My point is that comments shouldn't be used liberally. Code can and should be written with clarity in mind, especially if you share the codebase with lots of other devs.
Agreed. Not much is more annoying than a function which leaves you more confused after reading its name or does something different to what it says it should!