Last month I published a month of clean code. Now that another month has gone by I have more examples. For those that follow me on Twitter, you may have already seen a few of these.
Nevertheless, this post provides extra detail - more than I can cram into even 280 characters. So here's another collection of my recent "clean code" tweets.
Removing Comments
In this tweet I challenge you to remove comments. I pushed this long ago in my post on Removing Comments. In fact, I truly feel this single practice put me on the path to clean code.
I since stumbled upon a passage from Rob Pike which, quite effectively, summarizes this viewpoint perfectly:
[comments are] a delicate matter, requiring taste and judgment. I tend to err on the side of eliminating comments, for several reasons. First, if the code is clear, and uses good type names and variable names, it should explain itself. Second, comments aren’t checked by the compiler, so there is no guarantee they’re right, especially after the code is modified. A misleading comment can be very confusing. Third, the issue of typography: comments clutter code.
To emphasize these three points consider the following code before removing comments:
While there is nothing technically wrong with this code, I have drawn out several examples where comments don't hold value. When compared to the same code after removing comments we expose the opportunities for cleaner code.
For me, removing comments is not necessarily about achieving the mythical self-documenting code. More that my experience has shown me comments rarely benefit the code in-and-of-themselves. Pushing myself to limit their use or remove them completely has always yielded cleaner code.
🔥 Pushing yourself to remove comments is one of the best drivers towards clean code. Here's a few tips on how to sp… twitter.com/i/web/status/9…16:22 PM - 16 Nov 2017
Dead Code
In this tweet I touch upon a similar topic of dead code. While comments are one form of dead code, there are many more.
Dead code can be dismissed as not having an impact on the code. But nothing can be further from the truth. Not only does it disrupt the flow of future readers, but it may also affect their decisions. Over time, this can rot a codebase.
A static analysis tool or linter can go a long way to help identify dead code. Take an afternoon to run one and start removing dead code systematically - in separate commits that can be easily referenced and reverted in the event the code was not truly dead.
☠️ "Dead Code" can rot a code base over time. Here are a few common types of dead code. Be diligent and thorough ab… twitter.com/i/web/status/9…15:56 PM - 22 Nov 2017
Symmetry
In this tweet I introduce a higher level principle of symmetry. This is definitely more of an art form than my other tips. One that may take a long time to implement in code.
Nevertheless, symmetry is best shown by example.
It's important code symmetry appears throughout all aspects of the code - not just its structure. Symmetry should appear in names, format, syntax, even patterns. Truly symmetrical code is the cleanest code.
🔥 Symmetry is a hallmark of clean code. Symmetrical code is not only easy to read, but also predictable. Here are a… twitter.com/i/web/status/9…16:47 PM - 30 Nov 2017
Reasonable Returns
In this tweet I focus on return values. Using a reasonable return value can prevent writing code for checking or validating these values.
Determining a value may seem challenging in the moment. Often, the process of elimination helps. Let data types, method names, or related code guide your decision. In the end, unless your language handles null gracefully, any other value is a more reasonable choice.
Handling return values accounts for a lot of our code base. We can clean up this code by leveraging "reasonable ret… twitter.com/i/web/status/9…15:32 PM - 07 Dec 2017
Naming things is hard easy
In this tweet I share a few ways to make naming things a little easier. I touched upon the practice of naming things in my first post on writing clean code. These examples help demonstrate that practice in the real world:
In the end, I try to balance the name with the role. When naming a variable within a limited scope, I often use a short, common name. When naming an object referenced throughout the system, I often use a thesaurus to find a more contextual name.
🔥 Naming things is most certainly hard. I find full names aimed at relaying a human context yield the most readable… twitter.com/i/web/status/9…16:12 PM - 14 Dec 2017
Want more cleanup tips? Follow me on Twitter to get weekly tips, code tweets, and other randomness.
Top comments (10)
I always take more than one-third the time to sharpen the knives before starting a project. Really helps me. Code becomes so modularized, readable that it's always fun to come back and make changes. I reduced the frequency of commenting and stress more on renaming - makes really easy to understand for me and others. Also moderate indentation and refactoring helps!
How is this site free? :D
🙏
Awesome to see a collection fo your tips in article form! Keep it comin'!
"A misleading comment can be very confusion" this sentence is very confusion for me too :p (are you allowed to fix typos in quotes ?)
Great article by the way !
That was probably my typo transcribing it. Fixed!
Thanks!
Thanks!
Keep it up @gonedark !
I enjoy taking my time to just sit down and refactor old code like you do in these examples, I could do it for hours :D
Thanks, man! I have at least 3 more tips planned into the new year.
very helpful...loved it