Writing maintainable code

Question

What is the single most important factor for writing maintainable code (language independent)?

Answer 1

Good comments.

Answer 2

Documentation.

Answer 3

Good abstraction

Answer 4

Separation of Concerns (each method does one thing) - this stops Spaghetti code.

EDIT: (In response to Ash's comment) The key to maintainability is being able to quickly figure out what the code is doing and how to make changes in order to accomplish a task.

Having the code separated out so that each task is handled by a method dedicated to it makes this a snap.

For instance, if I want to change the way an elbow is bent on software for a robot, having a method named BendElbow makes it a no-brainer where the change needs to be made.

Answer 5

Good method names

Answer 6

Continuous refactoring

Answer 7

Automated unit tests.

You can slowly change the design of the code via refactoring if you've covered it with automated tests that tells you when it you are breaking existing functionality. Automated tests makes changing code less risky.

Answer 8

Good upfront design. Nothing can save a poor design.

Answer 9

Good comments can make even the worst spaghetti code 10x easier to maintain.

Answer 10

Don't do any of this stuff! Thanks to Roedy Green for the laughs though.

Answer 11

Unit testing hands down. If you unit test your code from the get go then you will have a test suite that you can run to validate the validity of your code whenever you make a change.

Also, when you are writing code with unit test then the methods tend to be smaller since they are easier to test. As well, it should encourage you to make your methods to a single task - again since it is easier to test that way.

Answer 12

Write it for other people to read. This means a combination of good names, good comments, and simple statements.

Once upon a time memory was scarce and cycles times were slow. programmers were encouraged to write complex single lines of code that did many things. Today memory is plentiful and cycle times are fast. You should write 5 lines of simple code people can follow instead of one line they cannot understand.

Good comments don't have to be long, but they must be helpful.

Also be consistent. Do not change styles in your code. For example don't change naming styles from one section to the next.

Answer 13

Good comments. Good comments help with abstraction by stating the code's intended purpose, bad comments just restate what the code is doing. Comments could actually come in the form of well-designed and named unit tests.

Answer 14

Consistency.

Answer 15

I don't think there is a single factor you can focus on. If there is I think it would have to be good judgement. Even well documented, easy to read code can be difficult to maintain if a developer used poor judgement during the design phase. No matter how good the documentation and unit test are, bad design of a production application can be almost impossible to fix.

You could also take a look at something like The Guide to Unmaintainable Code for ideas of what not to do. Informative and funny!

http://mindprod.com/jgloss/unmain.html

I have actually worked at companies that "standardized" on some of the things mentioned in there. You would think most of that stuff is just common sense, but you might be surprised.

Answer 16

Being on 1st or 2nd level support for the software you just wrote, for a year or two after release.

Trust me, I've been there myself. The "fear" that I may have to maintain or enhance my own code in a years time is always a great motivator for improving maintainability.

Answer 17

As I see it, the fundamental rule in writing maintainable code is that your code should be very easy to understand. This isn't as easy as it sounds, and you'll have to use all of the other techniques mentioned here to do it. It requires a certain amount of empathy because you'll have to learn how other developers see your code, and how it differs from the way you see it. A good way to get a grasp of that is to go back and look at some code you wrote a couple years ago.

Now, I suppose that it would be possible, theoretically, to write code that is very easy to understand and performs exactly the task it is intended for but which is also hard to modify in any way. I've never seen code like that, though.

Answer 18

Having good documentation. This includes code that is self-documenting (compartmentalized, descriptively named, and clear), good comments, a detailed design document that is accurate to the (most recently) final version of the code, and descriptive change notes in your source control.

If you asked for two, the second would definitely be unit tests. It was a hard choice between the two.

Answer 19

For me writing testable code(checkout Google testing blog) is the better maintainable code

Answer 20

There is no "single most important factor", it is a combination of several factors, as pointed out above.

Now, most of these rules can be condensed into: "write your code to read it later".
Or to paraphrase a funny yet good advice: "Write your code as if it must be maintained by an homicidal maniac knowing where you live."...

Answer 21

A consistent coding style. Things like method and variable naming conventions, styles and formats for comments, and even module/file naming.

Answer 22

I already voted up Matt's answer "Good Abstraction" but I wanted to add something.

Documenting it's all about explaining things. I'm all in favor of Doxygen and other automatic documentation tools but crude lists of functions in an API are just better than nothing.

If you want to have your code to be maintanable, describe your solution to the proper level of abstraction and refine that level up to the code so that it's obvious what it does.

Answer 23

I'd go with some of the others, ABSTRACTION. It also helps when you understand a few software patterns, GOF is a good place to start for that kind of stuff.

Answer 24

Plenty of whitespace. - High density code is hard to comprehend. If you have more than 6 lines wihtout a blank line, then that group is probably not a cohesive thought/idea/operation.

Good variable names - explanatory, but succinct. Huge variable names are as bad as tiny ones.

Answer 25

Read Code Complete- it covers everything about this from variable naming right through to the really big stuff and it is all necessary. There is no one thing.

My approach currently boils down to writing code to do the job that needs to be done ( not for every future job the code may need potentially to do ) using informative variable names and minimal variable scope and trying to make sure that my code needs as little supplementary documentation as possible. Sometimes this makes my variable and method names a little more verbose than they used to be ( my debugging output is very compreshensive when I use that ) but they are much easier to understand.

Maintainability is also generally an outcome of solid practice in other respects - if you are writing your code in a nice DRY way then problems are easier to find, if you've got a strong set of tests then you can see if maintenance changes are going to break anything.

Ultimately it's a question of trying to be thoughtful and writing for the future- code is only written once, after that it's all maintenance...

Answer 26

small, well defined functions and classes.

It's pretty easy to get used to other people's various coding conventions but if everything is in one giant class or function, my head explodes.

Answer 27

I would say the most important factor is DRY. glenatron Mention it already on his answer among other factors, but I think that's the most important one.

Answer 28

Without a doubt, writing code designed to be read by other people. This includes avoiding golf, mystery syntax, and thoughtful variable names that mean something. You can completely avoid writing any comments if the code is clean enough, IMO. \

[Picking a language with OO built in as opposed to tacked on helps too]

Answer 29

I guess writing maintainable code goes beyond code. I believe it is better to understand what the requirements were (and have it documented somehow, both functional and non-functional) and then have, like, a new employee, introduced to how that turned into code.

If someone knows why code turned out to be like that, then it gets easier to make it better and / or to expand it.

For more technical things (such as an algorithm) have it abstractly explained (goal, principle) and then commenting key parts of the code and / or pattern implementations.

One thing I do also is to create mini-labs, toolboxes and code templates inside my application so that people know what is the "standard" code necessary to do one thing or to expand another (leads to some copy/pasting but helps to produce more and better).

Answer 30

There is a tendency to write code thinking that the computer is your audience.

Strictly speaking, that's true since the code does have to work. But if you write with your human audience in mind, just that mindset helps to produce more readable code.

If you're worried that that will produce slow code, keep in mind that the most programs almost all of their time in very small portions of code. Start out writing for readability, then use a profiler to identify the right sections to optimise.

Answer 31

I prefer it when people prune and shape the code as it grows. Too often you find an original spine of decent architecture with a huge cludgy mess hanging off it.

Answer 32

Finding a good mentor. This person doesn't necessarily have to be a better coder than you, however they should be able to suggest other strategies for writing code properly. A good mentor will be to suggest many of the answers previously given to this topic. They can be a second set of eyes that let you know where your short comings are, while maintaining an encouraging, optimistic tone. They will also be flexible and constantly honing their skills as should you. That way when the next big paradigm comes up you'll be better able to separate the chaff from the wheat. This will be invaluable when Object Oriented Programming and Source Control are replaced by the next big thing (hard to imagine I know.)

Answer 33

Programming is performance; you should never forget who your audience is. "Code as if the person who ends up maintaining your code is a violent psychopath who knows where you live."

Answer 34

Strong, sensible conventions which are consistently applied. Things like conventions on where to start indexing, what end state to leave things in.

This makes it much easier to understand code, as all your code will behave in a way that is simpler.

This is at least one of my top tips.

Answer 35

• Record assumptions when you make them - two days later you will be taking these assumptions for granted, but the next person who maintains your code won't necessarily make the same assumptions, and will wonder why you did what you did...

• Code for people - the computer will do anything you tell it; code so humans can understand your code - who knows it might be you 6 months from now!