Thank you for your comment, as uncle bob likes to cite in his books many developers might not agree with all the rules and it's ok. With a couple of years of experience as a software developer in the .NET environment, I never ran into a scenario where I used external documentation generated from source code. If you work for an organization that requires external documentation like this then off course that would be necessary.
From a clean code point of view where methods and classes have single responsibilities, unit tests, etc. I don't agree with your statement that "every class, method, etc should have useful well written documentation comments".
I am a cloud application architect with 10 years' experience in software development in several languages, including Perl, Java and C#. I'm an Irishman living in Calgary, Canada. GitHub on @cubikca.
Location
Calgary, Canada
Education
BSc. Computing and Info Systems, Athabasca University
You say you've never used external generated docs, but I'd bet you've read Microsoft's dotnet docs and those are autogenerated from the source code and its documentation comments.
To each their own, but in the decade I've been building .Net libraries and applications, well written documentation has been extremely useful, both as an asset for clients and as a knowledge store for future devs when brought onto a project.
My main point is that documentation comments and code comments aren't the same thing. The idea proposed by Uncle Bob and the like, that comments are bad and should be replaced with self describing code, applies to code comments, not documentation comments, because documentation comments aren't for people reading the code, they are for people reading the docs.
Hey Jay, makes sense for people reading the documents in applications that exposes the documentation to have comments in classes and methods. In these cases for external documents, I would consider them as part of the non-functional requirements.
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.
Dear Jay,
Thank you for your comment, as uncle bob likes to cite in his books many developers might not agree with all the rules and it's ok. With a couple of years of experience as a software developer in the .NET environment, I never ran into a scenario where I used external documentation generated from source code. If you work for an organization that requires external documentation like this then off course that would be necessary.
From a clean code point of view where methods and classes have single responsibilities, unit tests, etc. I don't agree with your statement that "every class, method, etc should have useful well written documentation comments".
Those external comments are used to generate OpenAPI documentation using Swagger.
Yes I agree, it does make sense to comment code to expose documents to others. I would consider this a non-functional requirement.
You say you've never used external generated docs, but I'd bet you've read Microsoft's dotnet docs and those are autogenerated from the source code and its documentation comments.
To each their own, but in the decade I've been building .Net libraries and applications, well written documentation has been extremely useful, both as an asset for clients and as a knowledge store for future devs when brought onto a project.
My main point is that documentation comments and code comments aren't the same thing. The idea proposed by Uncle Bob and the like, that comments are bad and should be replaced with self describing code, applies to code comments, not documentation comments, because documentation comments aren't for people reading the code, they are for people reading the docs.
Hey Jay, makes sense for people reading the documents in applications that exposes the documentation to have comments in classes and methods. In these cases for external documents, I would consider them as part of the non-functional requirements.