How would you know if you've written readable and easily maintainable code?

Question

How would one know if the code he created is easily maintainable and readable? Of course in your point of view (the one who written the code) your code is readable and maintainable, but we should be true to ourselves here.

How would we know if we've written pretty messy and unmaintanable code? Are there any constructs or guidelines to know if we developed messy software?

Answer 1

Your peer tells you after reviewing the code.

_{Rationale: You cannot determine this yourself because you know more as the author than the code says by itself. A computer cannot tell you, for the same reasons that it cannot tell if a painting is art or not. Hence, you need another human - capable of maintaining the software - to look at what you have written and give his or her opinion. The formal name of said process is "Peer Review".}

Answer 2

Sometimes, the best way to know, is to come back to code you wrote six months ago and try and understand what it was written to do.

If you understand it quickly - it's readable.

Answer 3

It is:

1. maintainable if you can maintain it.
2. easily maintainable if someone else can maintain it without asking you for help
3. readable if someone else, on reading it, correctly understands the design, layout and intent

The real test for 1. is (as Alex in Paris and quant_dev say) that you can pick it back up after a few months doing something else.

The test for 2. and 3. is that someone else can pick it up, and figure out how to extend or fix your code while following the grain of your design. If they can't understand the design, how it relates to the problem space, or how your code is intended to be used, they'll hack a solution across the grain instead.

There are rules of thumb, principles (ie, rules of thumb someone wrote up nicely and gave a name) and all sorts of suggestions that may lead you in the right direction, or away from common pitfalls. None of them will guarantee the qualities you're asking for, though.

Answer 4

If your code follows the principles of SOLID and DRY and has a good set of unit tests around it, it is probably maintainable.

Is it readable? Read it. Do method and variable names make sense? Can you follow program logic without a problem? If the answer is yes, then the code is readable.

Answer 5

If you can understand it after 6 months, it's not bad.

Answer 6

The proof is in the pudding. Watch what happens after handing it off to a reasonably competent person. If they don't need to ask many questions relative to the difficulty of the code, you've done a good job.

This was an early lesson in my career. A mentor said, "Document everything, so that you can escape the program later on. If you don't anticipate questions when the answers are fresh in your mind, you'll have to figure them out when they're not."

Answer 7

Despite how it seems, there are some fairly objective measures you can consider. Books like C++ Coding Standards, Refactoring, and Clean Code have long lists of criteria to judge your code by, looking at things like meaningful names, function sizes, principles like coupling and cohesion, object design, unit testing, successive refinement, etc.

The list is too large to be amenable to a checklist, but you read the book and pick out a few key things to work on, then after several months read it again to improve further.

Answer 8

Reading How To Write Unmaintainable Code - Ensure a job for life by Roedy Green, laughing, and learning.

...how to write code that is so difficult to maintain, that the people who come after you will take years to make even the simplest changes. Further, if you follow all these rules religiously, you will even guarantee yourself a lifetime of employment, since no one but you has a hope in hell of maintaining the code...

The essay gives you numerous examples of how to write bad code, using plenty of funny examples. It continues to explain how to utilize Creative Miss-spelling, Reuse of Names, the highly appreciated technique of Reuse of Global Names as Private.

In a humorous way the essay teaches you how to avoid all of the examples of unreadable and unmaintainable code.

Actually, I found it hard to believe that anyone would write code with similarities to the examples in the text. That was when I was fresh from school. But, after working for a few years I see code from the text every day…

Answer 9

I would say one way to know would be if new team members can pick up the code, understand it, and modify it to fix defects / meet new requirements with relative ease.

Answer 10

How would one know if the code he created is easily maintainable and readable?

You can spot easy to maintain and readable code by looking for these properties:

1. Objects, methods and/or functions always do one thing.
2. Methods and/or functions are concise (as in "brief but comprehensive").
3. Objects, methods and/or functions do essentially what you think they are supposed to do based on their names.
4. Code that is destined for re-use is actually re-usable.
5. Last but not least, if you can immediately unit-test the code, you have likely written single-responsibility, modular code at the very least.

How would we know if we've written pretty messy and unmaintanable code? Are there any constructs or guidelines to know if we developed messy software?

1. If you are reading through a method and it isn't apparent what the intent was, this is inelegant at best and likely unmaintainable at worst.
2. If it doesn't seem simple, it probably isn't simple and that is a sign of unmaintainable code or code that will soon become unmaintainable.
3. If there is a lack of symmetry (consistency) across the codebase, you are likely looking at unmaintainable code.

Below is an example of code that obfuscates intent (comments removed from both):

ksort($params);
$first = true;
$oauthParams = '';
foreach ($params as $key => $value) {
  // only include standard oauth params
  if (strpos($key, 'oauth_') === 0) {
    if (!$first) {
      $oauthParams .= ',';
    }
    $oauthParams .= $key . '="' . urlencode($value) . '"';
    $first = false;
  }
}

The following is one example of how one might refactor the above:

public function buildXoauthParameters($params)
{
  ksort($params);

  $oauthKeys   = array_filter(array_keys($params), function($key){
    return preg_match('/^oauth_/i', $key);
  });

  $oauthParams = array_map(function($key) use($params){
    return sprintf('%s="%s"', $key, urlencode($params[$key]));
  }, $oauthKeys);

  return join(',', $oauthParams);
}

Answer 11

Readable and maintainable code: Code that, upon first-sight, a programmer can understand well enough to be able to easily:

• re-use it via its interface, or
• debug it, or
• change its behaviour. (add/remove a feature), or
• optimise it
• test it

This boils down to 'clarity'. i.e How many questions does the programmer have to ask of a particular segment of code before they are sure that they 'understand what it does well enough' to achieve the current task in hand without causing unexpected side-effects.

The book 'Code Complete, by Steve McConnell' goes into this in great detail.

He goes through various metrics that you can use determine if code is of good quality.

See an example here: http://books.google.co.uk/books?id=3JfE7TGUwvgC&lpg=PT376&pg=PT389#v=onepage&q&f=false

Answer 12

One point I'd share is if the code is built in "modules," and when I say that I mean that you can change one thing in a module and easily have it working with the whole. It eliminates effects between unrelated things. Also:

• Code is easy to reuse
• Your code is flexible (this ties in with building in modules)
• DRY - Don't Repeat Yourself

I highly recommend reading, The Pragmatic Programmer.

Answer 13

Here is a technique I like to use:

Show the code to one of your peer programmers and have them explain to you what it does. Watch for these things.

1) If they can't easily explain the purpose of a block of code refactor it.
2) If they have to jump to another section of code to understand the current section, refactor it.
4) Anytime you feel an urge to speak during the process, that section of code needs refactoring. (The code isn't speaking for itself).

Answer 14

Get someone who is not on the project to review the code. Eventually, you'll start to get an idea of what you are taking for granted. Your variable names may not be so obvious. Yes, you do need a comment to explain WHY you're doing this. Having a set of team standards and a review process to keep them in check, can go a long way.

Answer 15

In a single word, Experience.

To start, you need to have put in the ground work, so I can't recommend more highly that programmers should take the time to read books such as Refactoring, which will provide some of the more essential tools in a programmers arsenal that will improve your ability to maintain code, and Clean Code which has been written by some of the most highly recognizable talents in our field, and which describes nearly everything you need to understand in order to ensure your code is clean and readable.

No amount of reading however is a substitute for hard-earned experience. You really need to have worked with code for a while in order to fully appreciate the difference that attention to code quality can make. Through experiencing the pleasure of working with clean, well factored code, as well as the pain of working with code spaghetti, you learn to better understand what the authors of these books were really trying to teach you, but you do so in the wider context of real live production code, where the quality of what you do really matters, and impacts your ability to work easily with your code on a daily basis.

It also helps to have either a good mentor, or a peer with the experience to confirm that you are putting the effort into writing code to a high standard. This is just one reason why code reviews can be so useful. Using code checking and formatting tools can also be a very useful aid to ensure that you are keeping things clean. Nothing however compares to experience earned through years of writing software, such that you automatically find yourself writing code that is clean, readable, and structured simply for ease of maintenance, and all because you've made it a habit to apply best practices for so long.

Answer 16

Code is maintainable if you have, in some way, document the LOGIC you are using. It can be in comments, a separate text file, hand-written on paper, whatever. For every set of variables you use, you must document, in very few words, what the variable is supposed to go through in its life, in how many ways can it be initialized, where, when and by what code its supposed to change etc.

Another sign of good code is one that use as much less state as it can. This can be achieved by using lots of static methods, so that its ensured that they don't use any state/field.

Another sign is to have related code gathered at one place. Its too hard to maintain in practise a class that uses single-responsibility principle because of proliferation of lots of small cases. Your class can have many responsibilities if they are related and each has its own method.

Another sign is consistency. Every code has a convention: are you using stored procedures, if yes, do they do anything more than dml, i.e. do they have any logic (loops, conditions) in it? are you using triggers, cursors, bridge-tables vs parent-child relations etc? Whatever you do, be consistent. Don't sacrifice architectural consistency for fast development. When write new code, first go to any approach that works, then do some little tweaking for obvious edge cases, then do a little tweaking for some performance, then do a lot of refactoring till it follow the same architectural principles as the rest of your code.

Answer 17

Developing thinking in the architecture is a good practice. For example is good create mini-applications using hmvc architecture. So you can take each mini-application and use it in another environment.

For example, working with Codeigniter + hmvc extension you can create min-apps for:

• Manage users
  • crud
  • auth
• Manage files
• etc

So you can take one and use it in another application.