11 Tips for Writing Clear and Readable Code

Writing code that is easy to read and maintain is essential because you will read it many times after writing it, whether you are revisiting your own work or sharing it with others.

1. Keep methods short – A method should fit on a single screen, ideally 5‑20 lines, so you can see the whole context without scrolling.

2. Never reuse a variable for different purposes – Give each variable a single responsibility and make it constant when possible (e.g., const in C++ or final in Java) to improve readability and enable compiler optimizations.

3. Use self‑describing variable and method names – Names should convey purpose at a glance; avoid cryptic abbreviations. For example:

src - source
pos - position
prev - previous

4. Declare variables close to where they are used – Place the declaration near its first use to reduce the mental effort of tracking it across the file. For instance, the following code can be refactored:

int foo = 3;
int bar = 5;
// ... many lines using bar but not foo ...

baz(foo);

into:

int bar = 5;
// ... many lines using bar ...

int foo = 3;
baz(foo);

5. Avoid magic numbers – Replace literal numbers with named constants so the meaning is clear:

il < 4384

becomes

inputLength < MAX_INPUT_LENGTH

6. Treat each language kindly – Embrace the idioms of the language you are using instead of forcing patterns from another language. For example, printing "Hello world!" five times:

// Java
for (int i = 0; i < 5; i++) {
    System.out.println("Hello world!");
}

can be written more idiomatically in Ruby as:

// Ruby (loop style)
for i in (0..5)
  puts "Hello world!"
end

or even better:

5.times { puts "Hello world!" }

7. Do not fight conventions – Follow common coding conventions (e.g., camelCase for methods, PascalCase for classes, ALL_CAPS for constants, opening braces on the same line as the control statement) unless there is a compelling reason to deviate.

8. Beware of premature optimization – Focus first on writing understandable code; only optimize after profiling shows a real performance bottleneck.

9. Refactor tested code – After your code passes all tests, improve its structure. Use automated tests to verify that refactoring does not introduce regressions.

10. Do not over‑indulge in patterns – Design patterns are useful tools, but applying them indiscriminately can lead to overly complex code. Use patterns where they add clear value.

11. Learn by example – When adopting a new library or language, start with small, isolated examples to understand its concepts before integrating them into larger projects.

Source: http://www.vaikan.com/11-tips-for-better-code/#tip1