I am a passionate software developer attempting to learn in public.
I love learning and sharing and will be grateful for every opportunity to learn and improve.
@amabe_dev@mastodon.social
First of all, before writing a comment thing if you can provide the same content in the code.
One question that I find useful to know if a comment should be added or not is: Is it at the same level of abstraction as the code?
If it is at an higher level of abstraction, it provides context and might be useful. If it is at a lower level of abstraction, it provides constraints and might be useful. Both help explain a technical decision. And this the purpose of comments, to explain the why. That avoids making others loose their time figuring out a decision or trying something that we found inappropriate.
If it is at the same level of abstraction, it should not be added. It says the same thing the code says. And if it is needed to understand the code, I agree with you that it is a sign that refactoring is needed.
But thinking in level of abstractions might not be easy to grasp. Especially for beginners to whom those kind of tips might be useful.
Full-stack developer who loves sharing their knowledge and singing. Google Developer Expert for Web Technologies, public speaker, trainer and blogger. Writing about Web, a11y and code best practices.
Another tidbit that is useful in a comment is documenting special values in the inputs or outputs. No one wants to trace code to find out what are valid parameters or what meaning a nil or null takes in a parameter. Depending on your language the expected types can be critical as well.
Sometimes this is obvious, but if it isn't a comment is much easier.
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.
One question that I find useful to know if a comment should be added or not is: Is it at the same level of abstraction as the code?
If it is at an higher level of abstraction, it provides context and might be useful. If it is at a lower level of abstraction, it provides constraints and might be useful. Both help explain a technical decision. And this the purpose of comments, to explain the why. That avoids making others loose their time figuring out a decision or trying something that we found inappropriate.
If it is at the same level of abstraction, it should not be added. It says the same thing the code says. And if it is needed to understand the code, I agree with you that it is a sign that refactoring is needed.
But thinking in level of abstractions might not be easy to grasp. Especially for beginners to whom those kind of tips might be useful.
It's a good tip - thanks for that!
Another tidbit that is useful in a comment is documenting special values in the inputs or outputs. No one wants to trace code to find out what are valid parameters or what meaning a nil or null takes in a parameter. Depending on your language the expected types can be critical as well.
Sometimes this is obvious, but if it isn't a comment is much easier.