If we speak of some client code used only once, I would expect enough comments to guide me through the code structure, to explain the overall intent and explain the critical/strange code you may have to actually have.
Now would this code made reusable as a shared API I would expect a lot more. I would expect a clear facade as a design, witch each method, parameter etc fully explained. I would expect a guide on how to use the API, the common pitfalls and a few tutorials to show how to use it in practice... At least.
Comments are expensive to write and many people don't even read comments. But that's actually a problem, not a good thing. When I use a public API, same JDK or spring or whatever, I usually read what the API is saying. What are the exception cases, what are required on my parameters and also get lot of information on if it is thread safe, the performance, alternate methods in the API and so on.
I have seen that I can often be done with a non trivial problems very very fast this way because the code I read end up being both robust (being design to fit how the API is really working) and concise because I know when I need to test a null or not, when it make sense to catch an exception and when it is unecesary... And usually when other have to read it, it is quite clear for them.
Sometime they complain of the style used, I should use more inheritences, more class or less of something... But they find the code clear, understandable and maintenable. And that what we want, isn't it?
Fully commenting a code, including robust unit tests, including a few clear examples, relate to the overall design with other part of the code, refer to key concepts, key steps and maybe also explaining why it was done this way and what are the obvious extension points allows even a newcomer to understand what is happening much faster.
If we apply information theory on code, boilerplate, design pattern and so own are all noise and what we call incidental complexity. It may be obvious, may not require comments but the problem is also useless. A code should be meaningfull a so it would be expected to not have just noise. What is actually doing something would likely need some explanation and because the code is dry, the comment ratio would appear to be high.
But like we need to remove uncessary comments, we also really need to remove unecessary code.
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 would argue this depends what we speak of.
If we speak of some client code used only once, I would expect enough comments to guide me through the code structure, to explain the overall intent and explain the critical/strange code you may have to actually have.
Now would this code made reusable as a shared API I would expect a lot more. I would expect a clear facade as a design, witch each method, parameter etc fully explained. I would expect a guide on how to use the API, the common pitfalls and a few tutorials to show how to use it in practice... At least.
Comments are expensive to write and many people don't even read comments. But that's actually a problem, not a good thing. When I use a public API, same JDK or spring or whatever, I usually read what the API is saying. What are the exception cases, what are required on my parameters and also get lot of information on if it is thread safe, the performance, alternate methods in the API and so on.
I have seen that I can often be done with a non trivial problems very very fast this way because the code I read end up being both robust (being design to fit how the API is really working) and concise because I know when I need to test a null or not, when it make sense to catch an exception and when it is unecesary... And usually when other have to read it, it is quite clear for them.
Sometime they complain of the style used, I should use more inheritences, more class or less of something... But they find the code clear, understandable and maintenable. And that what we want, isn't it?
Fully commenting a code, including robust unit tests, including a few clear examples, relate to the overall design with other part of the code, refer to key concepts, key steps and maybe also explaining why it was done this way and what are the obvious extension points allows even a newcomer to understand what is happening much faster.
If we apply information theory on code, boilerplate, design pattern and so own are all noise and what we call incidental complexity. It may be obvious, may not require comments but the problem is also useless. A code should be meaningfull a so it would be expected to not have just noise. What is actually doing something would likely need some explanation and because the code is dry, the comment ratio would appear to be high.
But like we need to remove uncessary comments, we also really need to remove unecessary code.