59

I used to think I knew what this was, until I really started thinking about it... "maintainable"... what exactly makes code maintainable?

To me, if code must be maintainable that means we can expect to revisit the code to make some sort of change to it in the future. Code is always "changeable" no matter what state it is in. So does this mean code needs to be easy to change? However, if our code was scalable/extensible, there would be no need to directly change it, because it will "change" (adapt) for free and automatically.

I've also seen code maintainability used interchangeably with coding standards. Using a consistent coding pattern or style, does this really make code more maintainable? More readable and more consistent? Sure, but how does this improve the maintainability?

The more I try to think into this, the more confused I get. Anyone have a proper explanation?

Robert Harvey
  • 198,589
  • 55
  • 464
  • 673
void.pointer
  • 4,983
  • 8
  • 30
  • 40
  • 3
    You may get some insight from [this](http://programmers.stackexchange.com/questions/123293/what-hurts-maintainability) question as well as [this](http://programmers.stackexchange.com/questions/129327/how-to-keep-a-big-and-complex-software-product-maintainable-over-the-years) one. – Bernard Feb 13 '12 at 19:29
  • @Bernard: Thanks. I did read the latter one already, but it isn't specific enough. For example, when I hear someone talk about code "elegance", I know that means the code is probably simple, compact, and easy to read. Probably follows the KISS principle. When I hear someone talk about how their code is maintainable... uh... I kind of draw a blank on the real exact meaning of what they are saying. – void.pointer Feb 13 '12 at 19:32
  • 4
    Simple test: If **someone else** can read it after 6 months and make sense of it in less than 5-10 minutes, it's maintainable! :) – PhD Feb 13 '12 at 19:34
  • 1
    So then my definition would be: "Simple, self-documenting code that is pleasant to revisit". Does that about sum it up? – void.pointer Feb 13 '12 at 19:37
  • @Robert, yes... – Charles Salvia Feb 13 '12 at 20:32
  • 9
    @Nupul, even simpler test: if **you, the author**, can read it after 6 months and make sense of it in less than 5-10 minutes, it's maintainable! :) – Péter Török Feb 13 '12 at 20:48
  • I have no issues with the accepted answer, but shouldn't you wait longer than 2 hours to accept one? – Chance Feb 13 '12 at 21:50
  • "maintainable that means can [...] make some sort of change to it in the future". I think that is a gross misuse of the word "maintain". Maintain means "To keep in an existing state; preserve or retain." Making changes is not that. Code is symbols, and symbols don't requiere maintenance (unlike say, a carburetor). – Juan Perez Aug 15 '23 at 11:46

11 Answers11

67

Maintainability isn't a binary property, either being maintainable or not. It's a continuum. Roughly speaking, maintainability is inversely proportional to the amount of time it takes a developer to make a change and the risk that change will break something. Improving readability, coupling, or consistency all contribute to maintainability because it won't take as long to make any given change. Maintainability is easier to recognize by its absence, like when something you thought should take an hour ends up taking a week.

Karl Bielefeldt
  • 146,727
  • 38
  • 279
  • 479
  • Might want to add something about the risk of any given change - the more maintainable the code, the lower the risk of any particular change. – tdammers Feb 13 '12 at 20:49
  • I wish I could have picked 2 answers. Great answer. – void.pointer Feb 13 '12 at 20:55
  • 1
    "Maintainability isn't a binary property" Well said! – jmort253 Feb 13 '12 at 21:06
  • "Code that reads like a book" is great...but when that book should have taken an hour to read instead of a week...! – Sterling Hamilton Feb 14 '12 at 00:41
  • 1
    So "mathematically" it's TimeToImplement / Risk. This is the superior answer. =) – Mark Canlas Feb 14 '12 at 22:43
  • Switching to this as my answer because while I still really like the other response, this one just sums it up better and makes a lot more sense. Plus, the number of community up-votes voted it as the best answer as well. – void.pointer Apr 06 '12 at 16:01
  • **Maintainability** also needs [self-documented](http://stackoverflow.com/questions/209015/what-is-self-documenting-code-and-can-it-replace-well-documented-code) and [reusable code](http://stackoverflow.com/questions/268258/how-do-you-make-code-reusable), check the links for more info, Hope helps someone. – Shaiju T Oct 20 '15 at 19:45
  • Love the answer, but my hour might be your week. Following the book analogy, you might have trouble reading it if I wrote it in Swedish. – Martin R-L Jan 16 '19 at 13:07
  • Wait. So when you say "Maintenance" you actually mean "Improvement"? Because unlike a car, code doesn't requiere maintenance. Symbols don't wear out. I feel most programmers don't really understand the English language. – Juan Perez Aug 15 '23 at 11:38
25

Coding standards help in that your code base should be consistent, therefore easier to grok than a code base that contains multiple coding styles. Something that's easier to understand is easier to maintain.

To me, maintainable code really means code that reads like a book and is well documented.

Maintainable code is unit (and functional/integration if needed) tested so that if a change is made that introduces a knock-on effect, it's caught quickly and early, before the code's even checked in.

To me, maintainable code doesn't take advantage of quirky language features that 0.1% of the programming population is aware of (i.e. simple example: using an XOR swap instead of a temporary variable just because the author thinks "it's cool".

Maintainable code also implements sound architectural principles: DRY, SOLID, etc. It uses known design patterns and algorithms to solve appropriate problems.

Demian Brecht
  • 17,555
  • 1
  • 47
  • 81
  • I understand most of the points, except for your last. I'm a C++ developer, so my equivalent "quirky" feature would be template metaprogramming. I agree that code like this spread everywhere definitely hurts the ability to understand it and make quick, easy changes, but sometimes "quirky" code is necessary and unavoidable, so we do our best to hide it away under nice, maintainable interfaces and abstractions. Does this still go against the principle of having maintainable code? – void.pointer Feb 13 '12 at 19:35
  • 3
    @RobertDailey When used appropriately template metaprogramming is not a quirk. – Karlson Feb 13 '12 at 19:39
  • @RobertDailey: Agreed (sometimes it's necessary). As long as it's documented, then it's fine. I also agree with Karlson.. When used appropriately, it's not a quirk :) – Demian Brecht Feb 13 '12 at 19:41
  • I didn't mean to call it a quirk in general. For example, simple partial template specialization can be easy on the eyes. It's just that it's a symptom of a larger problem (lack of `static_if` and concepts). For example, if you made extensive use of it, like in the boost library, it would be a problem and can be very hard to read. Anyway, great information here. I might emphasize that "read like a book" means self-documenting code, or at least that's what I interpret it to mean. – void.pointer Feb 13 '12 at 19:46
  • 2
    @RobertDailey: "Read like a book" *does* mean self-documenting code, but as you pointed out, there may be numerous times throughout a codebase that, due to the specific problem, tricky code may need to be written, in which case it should be well documented. – Demian Brecht Feb 13 '12 at 19:58
  • Agreed, like in the XOR example, if you're going to use something clever, be sure to document it so your coworkers don't get stuck in the mud later when they have to work with your code and you've left the company for greener pastures :) +1 – jmort253 Feb 13 '12 at 21:05
  • While some of the attributes you list are highly correlated with maintainability, they do not define maintainability. Maintainability speaks to the cost of making changes to code, not about why or which practices may make changes cheaper or more expensive. – dietbuddha Feb 13 '12 at 22:59
  • 4
    @jmort253: Jim Larson on comments: "If you do something clever, brag about it. Not only will this inflate your ego, but it will also subtly tip off others as to where to look first for bugs." [link](http://www.jetcafe.org/jim/c-style.html#Comments) – ruakh Feb 13 '12 at 23:39
  • 2
    I would be very careful about that `read like a book` argument. I know exactly what you mean by that and I completely agree. However, I have heard that argument being used (against me, several times) in the following way: "I want ALL my logic to reside in this class/method; I want to be able to read it like a book when I come back to it." This is obviously not what we strive for; it is the exact opposite of maintainable code! – Guven Feb 14 '12 at 18:41
  • 1
    @ruakh Reminds me of this quote. “Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it.” - Brian Kernighan – Jaydee Feb 15 '12 at 15:45
  • The counter is often performance; e.g., in your example, ``XOR SWAP`` is very ``fast``. For this reason, it may win out under this definition of ``maintainability``. Some might argue that an XOR SWAP is quite maintainable and readable. – kmiklas Feb 27 '18 at 15:34
21

Code maintainability is the synergy realized when we apply all those coding axioms, rules of thumb, principles, etc. It is more art than science. To the extent that we have cooked in an appropriate amount of all these things, the code base is maintainable. Code is not maintainable (yes/no, on/off, either/or) just because you are able to change it (or not).

However, the acid test of maintainability is attempting to change the code. To the extent that the code resists, or doesn't resist, your interaction with it defines it's maintainability.

Maintainability has "abilities". Including, but not limited to

  • readability
  • understandability
  • changeability
  • testability
  • reliability
  • others?

How do we attain these abilities?

Through application of all those software principles and guidelines you've ever or maybe never heard of. For example:

  • Good comments
  • descriptive variable, method, class names
  • Limit methods to no more that a page in length
  • Maximize cohesion and minimize coupling
  • encapsulate that which stays the same
  • encapsulate that which changes
  • code layout/formatting guidelines applied consistently
  • One entry point only, and one exit point only.
  • ... and many, many, more ...

For good maintainability one must consider all of them, all the time, at every level of the code, and apply them in an (not "the") appropriate mix. Further, and I cannot emphasize this enough, no principle works best (or very well at all, perhaps) alone.

Seek Your Roads To Damascus

Several years ago two things came together. A set of programs that were literally unmaintainable and my discovery of Code Complete by Steve McConnell. This book was my bible in rewriting all that worse-than-failure code and the "before and after" comparison of the code was nothing short of revelation.

Find your roads to Damascus. It's a target rich environment.

Read Code Complete

I cannot overstate just how good this book is for learning fundamental software development principles.

radarbob
  • 5,808
  • 18
  • 31
  • "One entry point only, and one exit point only" is outdated, see http://programmers.stackexchange.com/questions/118703/where-did-the-notion-of-one-return-only-come-from – Péter Török Feb 13 '12 at 20:57
  • @PéterTörök, I'll see your thread reference and raise you every COBOL program I've ever seen. However, That thread illustrates a basic C++ idiom for coding a very simple test-and-return; and is fine as far as that goes (and it complies w/ the "one entry" half of that guideline). You'll also see immediate returning with input parameter checking - and when the alternative is a 40 line "else" statement, that's fine too. – radarbob Feb 13 '12 at 21:33
8

Maintainable code is code that exhibits high cohesion and low coupling. Cohesion is a measure of how related, readable and understandable code is. Coupling is a measure of how related code is, low coupling means that changing how A does something shouldn't affect B that uses A. Generally lower coupling means lower cohesion, and vice versa, so a developer need to find an appropriate balance between the two.

Maintainability is itself a measure of the ease to modify code, higher maintainability means less time to make a change. Coding standards are a way to achieve high maintainability and are developed as a result of previous experiences, they aren't universal and are dependent on developer preferences.

Ryathal
  • 13,317
  • 1
  • 33
  • 48
  • "Maintainable code is code that exhibits high cohesion and low coupling." My professors would say this a lot, and it's true. – jmort253 Feb 13 '12 at 21:06
  • 1
    -1 "Code that has low coupling and high cohesion is more likely to be maintainable" is true. Your assertion is not. – mattnz Feb 14 '12 at 03:00
6

Ask yourself some questions.
(or, as some may say, let's run together trough some scenarios)

  • How hard will it be for you to understand what you wrote?

    • Last week?
    • Last month?
    • Last year?
    • 27 years from now?

  • How hard will it be for a coworker to understand what you wrote?

  • In the unfortunate event everybody on your team is unavailable, but a fix must get trough in hours, and the only guy available for the job is a summer intern, how likely is he to succeed?

And then:

  • how hard will it be to apply a security fix to a random chunk of code?
  • how hard will it be to change a logic misunderstanding of the requirements?
  • how hard will it be to take care of usability/UX/cosmetic issue?
  • how hard will it be to adapt to the ever changing legal landscape?
  • how hard will it be to push some new marketable features in?
  • how hard will it be to port the whole thing to a different architecture?

And the best of all:

  • how hard will it be to adapt the whole behemoth to a new set of requirements for a client with a similar needs, but...?

This is more or less what maintenance is about. The latter is more about transforming the application into a product, maybe, but that's a need that's pretty typical to raise, with time.

"Best Practices":

  • Comments
  • Documentation
  • Diagrams
  • Consistent indentation
  • Coding Patterns

Are all just meant to make your code survive longer.

Coding patterns, in particular, help maintenance by making code reading less and less of a discovery, and more and more of a "Oh yeah, I saw that already, so the part I'm looking for should be... around here".

They should, obviously, be used with caution and never be copypaste/abused just for the heck of it.
It's not LEGO, it's more of a source of inspiration.

Chances are if you cannot relate someone's usage of some pattern with advantages in maintainability, they are not using them right. But stay assured that as a way of comparing different solutions and permitting faster response times in case of maintenance, they are theoretically sound.

ZJR
  • 6,301
  • 28
  • 36
1

I am surprised that no one mentioned McCabe complexity metrics. A high complexity metric is a real code smell when it comes to maintainability. It's sometimes necessary for a routine to be "complex" but usually indicates code which will be really hard to maintain.

Onorio Catenacci
  • 2,937
  • 3
  • 26
  • 37
1

Looking at this another way, All code is maintainable. The differentiating factor boils down to the effort required to maintain the code and the amount of technical debt the code represents in any given state.

Well factored code requires little effort to maintain, and when you do need to modify it will not impose a significant resourcing cost. Code that is difficult to read, too "clever" for its own good, poorly factored, or which does not suite the intention for which it was written, these are the types of code that incur higher costs to maintain, or to work-around if the cost:benefit makes it more expedient to avoid direct maintenance. Failing to maintain poor code greatly increases your technical debt, and increases the likelihood that the code will eventually be considered too costly to maintain.

Labeling code as maintainable vs un-maintanable can result in significant losses to your company, and can result in the stigma of project failure following its developers around like a bad smell for years. Changing the language to be more about effort, and less about the perception of maintainability can be more useful in the longer term, by helping to focus efforts on the problem before it becomes very difficult to manage.

S.Robins
  • 11,385
  • 2
  • 36
  • 52
1

When working with other developers who need assistance in understanding what maintainability means, I will ask them, "If you application crashes at 3:00 AM and you get called out of bed to fix it, is this code you would want to look at then?" You'd be surprised how this can change people's point of view.

Jared Shaver
  • 121
  • 2
0

maintaining code means taking that code and making a change to it to fix a bug or add a feature

maintainable code makes this process easier

making code maintainable means making it easy to understand (descriptive variable names, comments and documentation will help here) and making changes to it easy to make (patterns can make this easier, but it depends on the actual need)

ratchet freak
  • 25,706
  • 2
  • 62
  • 97
0

Maintainable is - to some extent - subjective. However, it's code that is written less with the writer's ego in mind and more with the recognition that at some point, someone is likely to have to revisit this code and modify it for reasons currently undefined. Very few codebases stay static for years on end.

What one person considers maintainable may be very different to another's view in some respects but some qualities I think it should include are:

  1. no hidden traps for the unwary in the future
  2. logic and rationale should be documented
  3. it should conform to some documented local standards

We have discussions here on the subject of documentation and commentary from time to time.

Code whose remit and logic is easy to follow should for the most part be easy to update as required with some caveats on original design considerations (which should be but ime never are documented adequately).

JJD
  • 103
  • 4
temptar
  • 2,756
  • 2
  • 23
  • 21
0

I have defined maintainability as: a measure of the effort required to change the functionality of application software. A measure of ‘effort’ must include time, resources and expertise.

In general any software development manager is familiar with this definition of ‘effort’ as it applies to creating software. The term ‘change the functionality’ applies to both enhancements as well as bug fixes. It might also be said that maintainable code is designed to be leveraged.

It does take some effort to create maintainable software. For what it is worth, I recently started a blog on the subject.

http://rdq-software.blogspot.com/

Robert Quist
  • 11