loading...
Cover image for Another month of clean code

Another month of clean code

gonedark profile image Jason McCreary Updated on ・3 min read

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:

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.

Code after removing comments

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.

Examples of dead code

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.

Examples of code symmetry

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.

Examples of using reasonable return 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:

Code sample for naming things

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.

Discussion

pic
Editor guide
Collapse
debdeepg profile image
Debdeep Ganguly

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!

Collapse
dangolant profile image
Daniel Golant

How is this site free? :D

Collapse
gonedark profile image
Collapse
david_j_eddy profile image
David J Eddy

Awesome to see a collection fo your tips in article form! Keep it comin'!

Collapse
clarkwinkelmann profile image
Clark Winkelmann

"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 !

Collapse
gonedark profile image
Jason McCreary Author

That was probably my typo transcribing it. Fixed!

Thanks!

Collapse
massivebrains profile image
Collapse
chrisvasqm profile image
Christian Vasquez

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

Collapse
gonedark profile image
Jason McCreary Author

Thanks, man! I have at least 3 more tips planned into the new year.

Collapse
joneskumwenda profile image
Jones Kumwenda

very helpful...loved it