Suggestion for writing more readable code?_问答_开发者

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.

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.

I suggest reading the following:

Pragmatic Programmer
Clean Code
Effective Java

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

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

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.

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

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.

Take a look at Code style used by Google Web Toolkit

It is really good

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

Single Responsibility Principle - SRP - One class must implement one responsibility.
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)
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.
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

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 "

Choose a coding style—any coding style—and use it consistently (along with anyone else on your team). If you use a consistent style you will become accustomed to it and develop code smells, which will tip you off to bad code.

There are many tools you can use to format your code automatically, and if you use an IDE it may have one built-in.

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

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:

If not done already, use version control.
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.