DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Maintainable Code vs. Common Code

What's the difference between maintainable and common code?

Erik Dietrich user avatar by
Erik Dietrich
CORE ·
Jun. 07, 16 · Opinion
Like (5)
Save
Tweet
Share
2.57K Views

Join the DZone community and get the full member experience.

Join For Free

Today, I’m going to answer a reader question that asks for my opinion on a blog post from medium.  In it, the other talks about what he calls “maintainable code,” but what I actually think of as “common code.”  Before I get started talking about these terms and the difference, however, consider the actual reader question.

I found this article and thought there was some interesting overlap with your 'Is Programming Art' article. What are your thoughts on this?

It  would probably help to read both pieces for background, but in case you don’t have the time, I’ll summarize the train of thought here.  In my post, the one to which the reader refers, I talk about the (small) intersection aesthetic appeal and software writing.  In the medium piece, the author, “Mr Galute,” draws a distinction between “brilliant code” and “maintainable code.”  Brilliant code, more or less, is the sort of code that requires a unique mind to dream up and a unique mind to understand, while maintainable code is the sort that any pro developer can maintain.  The overlap here is an interesting one, to be sure — this supposedly ‘brilliant’ code would seem to offer a specific kind aesthetic appeal in the same vein as solving a math problem in an unprecedented, but needlessly complex way.

Einstein Thinking Public Static Void

As for what I think of the post itself, I’m skeptical as to the existence of this ‘brilliant’ code, and I suspect the author is a bit too.  He makes a point that I really like in the first part of the post, and then, unfortunately, in my estimation, follows it up with something of a non sequitur in the form of examples of what he considers to be “maintainable.”  Here’s my quick summary of his post, if you don’t want to read it in its entirety.

I worked with a guy that was (or seemed) really smart.  He wrote crazy complex code and acquitted himself well in justifying it, so we assumed it was necessary.  This brilliant coder was also something of a bully, intimidating and chasing off anyone who dared question his special, unique approach.

But then he left, and we’re kind of screwed.  Nobody really understands what he did, which means that we either need to maintain code that we don’t get or else that we need to rewrite it.  Management learned its lesson from this, and realized that it’s better to have boring code that the group understands, rather than ingenious code that only one person understands.

I am absolutely with “Mr. Galute” up to this point, and I would probably even take a stronger position.  I’d argue that his difficult but ‘brilliant’ former colleague wasn’t actually particularly brilliant.  It takes a lot of cleverness to write code that both contains complex, unique approaches and that your colleagues can understand.  It doesn’t take as much cleverness simply to write code that no one understands and then to bluster a lot about it.  That’s the stuff of which expert beginners are made.

But then Mr. Galute goes on to explain what it means to write maintainable code.  This is something he calls “the 10 commandments of maintainable code in C” (though he argues that they are applicable to C# as well), and they round out the post.

  1. Thou shalt comment thy code.
  2. Thou shalt use white space.
  3. Thou shalt use meaningful variable names.
  4. Thou shalt use indentation.
  5. Thou shalt not squeeze all thy expressions into one line.
  6. Thou shalt include all the headers thy code needs.
  7. Thou shalt be explicit in they requests of the compiler.
  8. Thou shalt use methods and functions to break up thy code.
  9. Thou shalt use braces for thy loops and conditionals.
  10. Thou shalt use parentheses to control operator precedence.

After being completely with him up to this point, I found myself scratching my head as I read these.  Maintainability is the property of code that lets maintenance programmers make changes relatively quickly and with low risk.  Is that really what’s being described here?

If you’re a regular reader on this blog, you can probably imagine what would be first and foremost on my list of things that make code maintainable: automated unit tests.  If a method is well covered by unit tests, maintenance becomes a breeze — you know immediately if you’re breaking anything, so you can get in there and do what you need to with confidence.

Other properties of maintainable code include avoidance of excessive coupling, minimization of global/shared state, favoring immutability, minimizing path complexity, conforming to the Open/Closed Principle, and generally abiding by the Principle of Least Astonishment, to prevent your code from containing mental landmines.  Thus I would imagine commandments of maintainable code to address things that affect how you reason about code.  These ‘commandments’ mostly don’t.

In fact, 6 of them are entirely superficial: (1), (2), (4), (5), (9), and (10).  I say this because those are all properties of the code that can be auto-fixed easily by an IDE plugin.  That is, with things like “use indentation,” you can literally have your IDE fix that for you every time you save a file.  So, how serious a barrier to maintainability can these things possibly be?  If you don’t like the way a piece of code looks vis a vis these items, it costs you only the fraction of a second required to hit a keyboard shortcut — hardly a maintainability deal-breaker.

And yet, the things he’s talking about do matter to people.  They’re typically the source of a lot of squabbling among teams trying to normalize on a coding standard, and they can be frustrating when you’re trying to read code.  But they’re frustrating not because they’re wrong or because they intrinsically cause maintenance difficulty — they’re frustrating because they’re not what you’re used to.

Programmer with Steam Coming Out of Ears

It is for this reason that I propose the term “common code.”  Maintainable code is code that can be modified cheaply, quickly, and with low risk.  Common code is code that conforms to the group’s standards or, absent that, to common industry practice.  Writing maintainable code is an important competitive advantage, from a business perspective.  Writing common code is common courtesy to your teammates.

I would advocate that people write both maintainable code and common code.  But I’d caution against confusing the two.

If you have a question you’d like to hear my opinion on, please feel free to submit.

code style

Published at DZone with permission of , DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • DevOps Roadmap for 2022
  • PostgreSQL: Bulk Loading Data With Node.js and Sequelize
  • Asynchronous HTTP Requests With RxJava
  • Secrets Management

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends: