Suggestion for writing more readable code?

Question

What tips/suggestions do you have for writing more understandable code?

I've been somewhat frustrated by the lack of structure and bad format of some code I've been maintaining lately and would like to propose a series of guidelines for writing more understandable code.

Any suggestion might help, no matter the language.

Regards.

Answer 1

I suggest reading the following:

• Pragmatic Programmer
• Clean Code
• Effective Java

Answer 2

Try these:

• Minimize nesting - the less nested control blocks the easier the code will read.
• Use temporary variables - while they can make your code look clunky sometimes they can also greatly improve readability.
• Break down big functions - break down large functions into small, single-responsibility functions that can be easily understood and tested.

Answer 3

"If you need more than 3 levels of indentation, you're screwed anyway, and should fix your program" - Linus Torvalds

Answer 4

There are many code-style guidelines and heuristics, but the best way to ensure readability is when someone writes code, someone else should read it, and then criticize it.

Answer 5

1. Naming - functions, variables, classes, etc... A good name goes a long way towards making code readable. The name should be descriptive and clear and make sure to update the name if the purpose of the thing changes.

2. Break down complicated functions - My rule of thumb is that if I can't fit an entire function/method on the screen at the same time it probably is doing too much and needs to be broken up.

3. Readability over cleverness - You will impress more people with code they can read and maintain 5 years later than you will with clever uses of obscure features of the language

I could go on but this is a good start.

Answer 6

I liked these books:

• Clean Code
• Refactoring
• Agile Software Development

You should also read code. If the code is hard to read, ask yourself what exactly the author did or didn't do that makes it hard to understand, and more importantly, how you can use what you've learned to write better code yourself.

Answer 7

1. Stay DRY - Don't Repeat Yourself
2. Keep methods small
3. Test as you go - your unit tests will help your design, act as documentation, and keep your code working properly.
4. Name methods and variables carefully - a well-thought out name is better than a comment.

Answer 8

It seems the question is really about transforming unreadable code into readable code which is different from writing new readable code.

Before doing anything else:

1. If not done already, use version control.
2. If not done already, use automated testing.

In general, the customer does not care how readable the code is. The customer cares a lot about whether the software functions as expected.

When you are initially handed unreadable software to maintain, you have a scapegoat for software bugs. But if your predecessor fixed a bug at the customers request and you inadvertently delete the fix (it was probably very unreadable), then the customer will not have much patience.

Answer 9

Take a look at Code style used by Google Web Toolkit

It is really good

Answer 10

The key to writing maintainable code is to follow some fundamental code design principles:

1. Single Responsibility Principle - SRP - One class must implement one responsibility.
2. DRY - almost reciprocal to SRP - Don't repeat Yourself - in other words don't let the same responsibility be implemented by multiple classes (for it would result in repetition of the same code)
3. Make vertical slices of the application and call each slice a module. Come up with a modular structure with clear cut dependencies between modules. Publish a module structure for the project and enforce that the team complies to it. Obviously no cyclical dependencies. Use a tool like maven or apache ivy for dependency management during builds.
4. Have an approach to implement non functional requirements as horizontal requirements using strategies such as AOP, decorators etc.

With these things in place, most of the code would become maintainable. Each of the points above is itself pretty involved. I absolutely love this book.

Look at blogs etc where these things are discussed. All the best

Answer 11

Since you are already maintaining a large code base, having a good IDE and enforcing standard formating on all will help. To change existing code into more readable is much more than that.

Start from book "Refactoring: Improving the Design of Existing Code - Martin Fowler , Kent Beck , John Brant , William Opdyke , Don Roberts "

Answer 12

A few come to mind:

• Don't unnecessarily put this in front of methods such as:

this.doSomething();

• Don't use Hungarian such as:

private int mCount;

• Declare local variables close to where they are used, preferably as late as possible