I recently wrote an article around the importance of automating the coding standards around your codebase.
Whether that be tabs vs spaces, the num...
For further actions, you may consider blocking this person and/or reporting abuse
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.
Nice article, but you described the usecase without a presenter, included in clean architecture. In an API scenario it is important to decouple the DTO (your response) returned by use case and separate the presentation concerns
Just a heads-up: the info graphic looks awful in Dark Mode, and I will never not use Dark Mode. :)
Thanks Kelly :-) I always forget about dark mode
It looks great now!
Thanks :-)
Hi James,
Awesome article. But I can't build your C# code because it's missing a project. Can you commit that part?
Hey, thanks Rafael and thanks for letting me know it's not working.
Do you have detail on what's missing, I have no outstanding commits?
Looks like there is a project CleanArchitecture.UseCases that isn't in the repository. The CleanArchitecture.Infrastructure references it.
Hey Rafael, thanks for letting me know :) I've just updated the repo, deleted my local copy and re-cloned and all seems ok now.
I'm just updating the README file as well, which should give more detail on running the code.