Nice article but I have an objection.. I see that you are using comments/summary almost everywhere but before talking about clean architecture principles we have to have in mind the clean code principles.
To the point, the code in general should be descriptive itself. The parameters, functions/methods, classes, variables etc should have a meaningful name that matches the purpose of its existence, so no additional commenting should be used.
So, for example, this shouldn't exist:
/// <summary>
/// Gets or sets the applicants name.
/// </summary>
public string Name { get; set; }
Reading the code should be like reading a story..
Although, the summary comments is a good practice to document the code at the API layer so it is clear what the the exposed endpoints are handling, what response codes they return etc. It's handy especially using swagger
Hey George, I really appreciate you taking the time to write such a detailed response.
Your point on the comments is a battle I have with myself almost every single day.
I completely agree with the clean code principles (you'll notice none of the content of the code contains comments). Tidy self documenting code is something we should all strive for.
That said, well documented public endpoints allows people to use the Core library without actually looking at the code. So I think there is a worthwhile trade off there.
Thanks for the input though, I do always appreciate it!
True full stack in #fintech. Analysis, solutionizing, developing and delivering.
Mostly working in dotnet and javascript, with a passion for process optimising!
For the sake of constructive debate, I always advocate for commenting - Where sensible.
If you have worked with a large (as in Enterprise) code base of substantial complexity, coming back to fix a bug in some 10 year old code is a lot easier if the methods have basic descriptions in the summary explaining usage. Especially so if there are override methods in play. You _could _argue that if a method isn't obvious and you are following the SOLID principles you wouldn't get this issue, but that's a debate for another time.
Of course, There are _many _scenarios where I would agree fully with you. We have fairly trivial code in some places which comments would be almost useless. (i.e a method named "GetAgeFromDate").
With a super mature product which has seen many developers come and go, all with their own coding style (Even if we do have "guidelines"!), I have had comments save me entire days of debugging.
I think it's a case of being sensible and knowing when is a good time to add comments and when isn't.
Great input, thanks Rich. I completely agree with all the above.
I tend to work on the rule of thumb that any public properties/method signatures should have a brief summary of intent. However the contents of the method itself should follow the clean code guidelines more strictly.
I think the important thing is just being flexible and treating each scenario differently. As you mention, a method called GetAgeFromDate doesn't really need any commented explanation.
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.
Nice article but I have an objection.. I see that you are using comments/summary almost everywhere but before talking about clean architecture principles we have to have in mind the clean code principles.
To the point, the code in general should be descriptive itself. The parameters, functions/methods, classes, variables etc should have a meaningful name that matches the purpose of its existence, so no additional commenting should be used.
So, for example, this shouldn't exist:
Reading the code should be like reading a story..
Although, the summary comments is a good practice to document the code at the API layer so it is clear what the the exposed endpoints are handling, what response codes they return etc. It's handy especially using swagger
Thanks!
Hey George, I really appreciate you taking the time to write such a detailed response.
Your point on the comments is a battle I have with myself almost every single day.
I completely agree with the clean code principles (you'll notice none of the content of the code contains comments). Tidy self documenting code is something we should all strive for.
That said, well documented public endpoints allows people to use the Core library without actually looking at the code. So I think there is a worthwhile trade off there.
Thanks for the input though, I do always appreciate it!
I absolutely understand that and my apologies if my comment bothered you. That wasn't my intention anyway.
In any case, have a great day!
It didn't bother me in the slightest :-) I always like having a discussion about things and try to reply to all comments.
Same to you :-)
For the sake of constructive debate, I always advocate for commenting - Where sensible.
If you have worked with a large (as in Enterprise) code base of substantial complexity, coming back to fix a bug in some 10 year old code is a lot easier if the methods have basic descriptions in the summary explaining usage. Especially so if there are override methods in play. You _could _argue that if a method isn't obvious and you are following the SOLID principles you wouldn't get this issue, but that's a debate for another time.
Of course, There are _many _scenarios where I would agree fully with you. We have fairly trivial code in some places which comments would be almost useless. (i.e a method named "GetAgeFromDate").
With a super mature product which has seen many developers come and go, all with their own coding style (Even if we do have "guidelines"!), I have had comments save me entire days of debugging.
I think it's a case of being sensible and knowing when is a good time to add comments and when isn't.
Just my 2c
Great input, thanks Rich. I completely agree with all the above.
I tend to work on the rule of thumb that any public properties/method signatures should have a brief summary of intent. However the contents of the method itself should follow the clean code guidelines more strictly.
I think the important thing is just being flexible and treating each scenario differently. As you mention, a method called GetAgeFromDate doesn't really need any commented explanation.