I have seen too much code whose purpose is never explained, and been told too many times to "read the code", as if by some process of clairvoyancy that will tell me what was in the mind of the coder.
If a method is called "setMessage()" and you change its functionality so it appends instead of replacing, you don't leave the name unchanged, do you? So why are comments any different?
It's the responsibility of all programmers to ensure their code remains readable and its purpose is clear. As with method names, without appropriate comments the purpose is often far from clear. Don't duck the responsibility.
Full stack developer with a focus on front-end development and a strong skillset in JavaScript technologies, including React and Node.js. Proficient in building modern and responsive web applications.
It's true that all programmers need to ensure that their code remains readable, and again, this could also be the one more reason to use descriptive function names instead of comments.
These are some reasons why I think that descriptive names are better than comments:
Comments inside a function used to describe what some block of code does can lower readability.
If we need a comment to describe a block of code, then this block of code can be moved to a separate function.
A function should do only the one main thing which should be easily described by its name.
A large number of comments also lower the readability.
There is more chance to see that some function has a bad name than that comment is bad.
Functions are recognized by modern tools and IDEs, while comments are not. This can help us to recognize that name is bad even outside of a file the function belongs.
Additionally, functions should be short enough that comments are not needed.
However, sometimes comments could be our friends:
public functions should be commented (documented) especially in public libraries/packages - this could help us to understand what those are doing without the need of looking at source code.
todo's - but please, do not push it to the repository or rely on someone else to fix it or to see it (I used to see some todo's more than 2 years old). It is better to create a new ticket/task/issue.
It's not easy to make fixed rules about these things, but I do believe that too little documentation is the enemy of maintainable code. In the end we have to rely on the professionalism and common sense of the programmer. If (s)he doesn't have any we're doomed anyway.
I think I'm generally in agreement with what you say. I advocate the implementation of 'user stories' as high-level code, if only as a set of single-use functions, to match (where possible) the project brief supplied by the client. Then it's quite clear what the intention of the program is without the need for excessive documentation. That tends to answer the "why?" question that the code itself rarely reveals.
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 have seen too much code whose purpose is never explained, and been told too many times to "read the code", as if by some process of clairvoyancy that will tell me what was in the mind of the coder.
If a method is called "setMessage()" and you change its functionality so it appends instead of replacing, you don't leave the name unchanged, do you? So why are comments any different?
It's the responsibility of all programmers to ensure their code remains readable and its purpose is clear. As with method names, without appropriate comments the purpose is often far from clear. Don't duck the responsibility.
It's true that all programmers need to ensure that their code remains readable, and again, this could also be the one more reason to use descriptive function names instead of comments.
These are some reasons why I think that descriptive names are better than comments:
Comments inside a function used to describe what some block of code does can lower readability.
If we need a comment to describe a block of code, then this block of code can be moved to a separate function.
A function should do only the one main thing which should be easily described by its name.
A large number of comments also lower the readability.
There is more chance to see that some function has a bad name than that comment is bad.
Functions are recognized by modern tools and IDEs, while comments are not. This can help us to recognize that name is bad even outside of a file the function belongs.
Additionally, functions should be short enough that comments are not needed.
However, sometimes comments could be our friends:
public functions should be commented (documented) especially in public libraries/packages - this could help us to understand what those are doing without the need of looking at source code.
todo's - but please, do not push it to the repository or rely on someone else to fix it or to see it (I used to see some todo's more than 2 years old). It is better to create a new ticket/task/issue.
It's not easy to make fixed rules about these things, but I do believe that too little documentation is the enemy of maintainable code. In the end we have to rely on the professionalism and common sense of the programmer. If (s)he doesn't have any we're doomed anyway.
I think I'm generally in agreement with what you say. I advocate the implementation of 'user stories' as high-level code, if only as a set of single-use functions, to match (where possible) the project brief supplied by the client. Then it's quite clear what the intention of the program is without the need for excessive documentation. That tends to answer the "why?" question that the code itself rarely reveals.