A well written unit test explains the contract of the code, what is it supposed to be doing.
And I am in the camp that comments are the exception instead of the rule. I do make a distinction between API documentation/architecture documentation and comments that explain what you are actually doing in the code.
I did expect to see examples in this blog so there was something concrete to agree or disagree with.
Thanks for the feedback. I think unit tests can definitely provide a lot of clues, especially with all of the possible inputs good (and maybe bad) inputs.
High-level documentation I agree should be distinguished from comments, though I believe some tools use class and method comments and such to generate API docs, so it would accomplish two things at once. Plus if I'm reading through the code, it would be easier to just see the comments right there instead of going elsewhere to reference the design docs.
Example is a good idea. I will think of something appropriate to illustrate the purpose of a comment and how it might be useful.
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.
A well written unit test explains the contract of the code, what is it supposed to be doing.
And I am in the camp that comments are the exception instead of the rule. I do make a distinction between API documentation/architecture documentation and comments that explain what you are actually doing in the code.
I did expect to see examples in this blog so there was something concrete to agree or disagree with.
Thanks for the feedback. I think unit tests can definitely provide a lot of clues, especially with all of the possible inputs good (and maybe bad) inputs.
High-level documentation I agree should be distinguished from comments, though I believe some tools use class and method comments and such to generate API docs, so it would accomplish two things at once. Plus if I'm reading through the code, it would be easier to just see the comments right there instead of going elsewhere to reference the design docs.
Example is a good idea. I will think of something appropriate to illustrate the purpose of a comment and how it might be useful.