It's so important that you mentioned people who live with different conditions, like ADHD. This can, indeed, make the process of analyzing and understanding code even harder.
I don't think comments are the nemesis of good, reusable, and maintainable software. However, I do believe that your code should be self-documenting (to a certain extent). What I mean by that is that comments should be your last option. Let me explain.
The issue with leaving comments in the codebase is that they often are used as a simple fix for non-descriptive variable names or inflexible design that violates principles like the SOLID principles. Comments also tend to become technical debt, since they are rarely updated when the code evolves. So, here's my thought process when I feel that I have to leave a comment in the codebase:
The best form of documentation is self-descriptive, easy-to-understand code. With that in mind, I ask myself if I violated any software design principle. If yes, I try my best to refactor my code so that it is as clear as possible.
If refactoring is not enough, another great way of supporting and documenting your code is with... documentation! There is so much to be said about documenting that I wrote an article on how to document your work as a software engineer and why it's such an important skill to master. Check it out 👉🏻 Conquer Your Fear of Documenting in 9 Simple Steps
If, refactoring and technical documentation are still not enough, that's when I allow myself to insert comments in the codebase. Depending on the programming language that you use or the IDE, there are different standard approaches and formats you can use so that your comments don't end up being tech debts down the road.
Bottom line, comments can be very useful to visually help you understand each and every step of your code, especially when implementing new features. However, when you're collaborating and/or when you're working on a prod environment, there are several guidelines to adhere to in order to maintain good, readable, and clean code that is scalable and easily maintainable. These guidelines put a bit of order in the chaos that can arise when coding in a shared codebase.
# outro
With that in mind, you can turn tech debts into powerful assets!
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.
It's so important that you mentioned people who live with different conditions, like ADHD. This can, indeed, make the process of analyzing and understanding code even harder.
I don't think comments are the nemesis of good, reusable, and maintainable software. However, I do believe that your code should be self-documenting (to a certain extent). What I mean by that is that comments should be your last option. Let me explain.
The issue with leaving comments in the codebase is that they often are used as a simple fix for non-descriptive variable names or inflexible design that violates principles like the SOLID principles. Comments also tend to become technical debt, since they are rarely updated when the code evolves. So, here's my thought process when I feel that I have to leave a comment in the codebase:
The best form of documentation is self-descriptive, easy-to-understand code. With that in mind, I ask myself if I violated any software design principle. If yes, I try my best to refactor my code so that it is as clear as possible.
If refactoring is not enough, another great way of supporting and documenting your code is with... documentation! There is so much to be said about documenting that I wrote an article on how to document your work as a software engineer and why it's such an important skill to master. Check it out 👉🏻 Conquer Your Fear of Documenting in 9 Simple Steps
If, refactoring and technical documentation are still not enough, that's when I allow myself to insert comments in the codebase. Depending on the programming language that you use or the IDE, there are different standard approaches and formats you can use so that your comments don't end up being tech debts down the road.
Bottom line, comments can be very useful to visually help you understand each and every step of your code, especially when implementing new features. However, when you're collaborating and/or when you're working on a prod environment, there are several guidelines to adhere to in order to maintain good, readable, and clean code that is scalable and easily maintainable. These guidelines put a bit of order in the chaos that can arise when coding in a shared codebase.
# outro
With that in mind, you can turn tech debts into powerful assets!