Introduction
Writing clean code is a fundamental skill for every software developer. Clean code not only makes your codebase more mainta...
For further actions, you may consider blocking this person and/or reporting abuse
I am not sure what's good in that example, as the code is self-explanatory. :-)
I could see a good example like that:
The comment explains why value needs to be converted and prevents questions like "We don't need to convert value to number here".
Even then I'd refactor it into its own function and call it something like
fixBrokenApiReturnType
.The function name
fixBrokenApiReturnType
does not explain why it needs to be fixed. I'd eventually add a comment with the JIRA (or the like) ticket ID.Don't forget to JSDoc the living **** out that function as well xD
@barrymichaeldoyle Roger that xD
Passive-aggressive function names, love it 😆 (I'm not being sarcastic, seeing people's exasperation come through in their comments/naming always gives me a good chuckle, and I've been known to do the same myself on occasion)
Even in your example, the comment isn't totally necessary. If that's JavaScript, it's clear what's happening. If it's another language, we could just cast to string, and that would be clear from the code. For instance:
int totalUsers = (int) users;
My example code is clear, but only from the code perspective. The question is, why would you convert an incoming value to a number here? And to clarify, an additional comment would help here.
Please give the credit to the author of this content...
As I was reading this, I knew it was directly from Clean Code: A Handbook of Agile Software Craftsmanship... So I pulled the book from my desk and confirmed it
en.m.wikipedia.org/wiki/Robert_C._...
Hi @camco
I appreciate your comment. However, I would like to clarify that the content I provided is a reflection of general knowledge and widely accepted industry practices. It has not been directly copied from any specific source, including 'Clean Code: A Handbook of Agile Software Craftsmanship.'
Now this is a ChatGPT written comment if I ever seen one...
So true 🤣
I'd say this is not always true. Just spitting everything into smaller functions can lead to way too much fragmentation and it requires you to jump across several functions and files to grasp the full picture. The same can happen because of the DRY principle.
Sometimes it makes sense to duplicate the same code for a) readability reasons and/or b) because it serves a different purpose and just happen to look the same.
In short: those things lead to premature abstraction (YAGNI is often the better approach)
I conceptually divide the classes into two categories: master and utility.
The master code looks like this:
In this way, just reading the master code you can have a full picture of the flow and what it does.
On the other hand, often I see code like this:
This is a code impossible to read and to maintain
Thank you for your input. You've highlighted a valid point about the potential drawbacks of excessive code fragmentation and strict adherence to DRY. Balancing clean code with readability and avoiding premature abstraction is indeed a nuanced challenge. Context and project requirements often dictate the best approach. Your insights contribute to a valuable discussion on software development principles
Good artical, but your examples are off.
Good comments explain "why" not how or what. Method names explain what. Method bodies explain how. It's often not taught like this as introductory programming books often use comments to explain what some piece of code is doing. Once you can read code you should not need that help.
Changing a method to have a discount argument is not an example of refactoring as it changes behaviour. In TDD, the red, green, refactor cycle, relies on the tests written in red, that you made pass in green. If you add behaviour in refactoring, you won't have a test for it. Refactoring is defined as changing the design or structure without changing the behaviour.
Keep up the work.
Thanks for the feedback, Your insights are valuable.
catch ( ex ) {
console.error(...)
}
This should only be done at the top level of your application, and in most cases it is already being done, eg, by your web container or CLI framework.
If the only thing you can do with an exception is reporting it, then IGNORE it and let the top level deal with reporting. This will do it in the way that was configured for the entire application (eg, it sends it to the app logger).
If you can detect a more specific anomaly, eg, your case where you have something like "Invalid input %s for ", then RETHROW ANOTHER exception, ATTACHING the original one (the stacktrace is very valuable for debugging).
If you can recover from an exception, then do it in the catch and log the workaround as a warning (eg, "Config file not found, using default config"). If you need to interrupt the normal flow, then catch and rethrow or return, DO NOT catch and let your regular code to continue (with bad data, inconsistent/insecure state, etc).
I see wrong ways of dealing with exceptions (empty catch, console.error(), out.println () ) all the time and it's so time-wasting and frustrating.
I have been doing this for 47 years, and clean code has seldom been a fundamental skill.
I submit that if you're properly naming your variables and other structures, that constitutes good commenting. Comments should be rare, because your code should be so readable, you don't need them.
I know you aren't invoking Uncle Bob, here, but I'm going to. He covers that concept right in preface of the book, before he ever digs into the subject.
Thank you Mark,
Very Insightful 🔥👏👏
Thank you Daniel
well explained article 👍
Good
Very informative, thank you
Well explained !
Thank you chief 🔥
Maturity is when you start writing clean code. I am immature 😅
I'd say maturity is when you realize some clean code principles are not always rights
Well explained!
Perfect
Your understanding level is so much cool. really I am enjoying this article
Printing to the console when catching exceptions is not error handling, it’s a form of exception swallowing and is a common bad practice that will typically result in unpredictable behaviours.
Thanks for sharing.
Very Insightful.
Very Insightful
Also you could pick up other point of veiw on explaining principles here codingstories.io/space/clean-code
Thanks alot @asomlev
I am glad to say I do follow all these steps.
It's been an educative read for me. Thank you, Mark!
This is great. These are simple stuff but will boost you productivity and those around you.
Keep every version...
Storage is dirt cheap
It's easy to use a Diff app to find those pesky changes.
I write dirty code and it surprises me even.
archive.org/details/spectate-01-se...