Another month of clean code

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.

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.

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.

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.

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.

Want more cleanup tips? Follow me on Twitter to get weekly tips, code tweets, and other randomness.