What characteristics or features make code maintainable? [duplicate]

Question

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?

Answer 1

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.

Answer 2

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.

Answer 3

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.

Answer 4

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.

Answer 5

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.

Answer 6

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.

Answer 7

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.

Answer 8

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.

Answer 9

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)

Answer 10

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/

Answer 11

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).