Improving Code Readability

Question

When it comes to code documentation, it is usually accepted that code should explain itself, and inline code documentation (excluding public API documentation) should only explain meta-code issues such as workarounds, explanations on why specific implementations were chosen, etc.

How do you accomplish making your code more readable and more explaining itself?

---

Edit: in addition to general comments, I'm also looking for specific tips. So if you say "short but meaningful variable names", it would be nice to also get a helpful tip as well (e.g. "use the three-word principle").

Answer 1

• Consistent formatting style
• Good use of white space
• Using short, but meaningful names
• Not too many comments (as you mention), but when I do, comment the whys of the code, and if applicable, the why nots (why wasn't some other implemention used, especially if it seems like it should be obvious to do so).
• Don't optimize code until a profiler tells me its slow or inefficient

Answer 2

Have a Coding Convention between you and your colleagues. Starting with indention, covering brackets until "where does the curly bracket come: new line, same line?"

In Visual Studio one can choose and fix this style. It helps all others in your team reading the same code. It also makes history tracking in a versioning system much easier when you don't have to distinguish between 'empty' edits (change of style) and real edits.

Answer 3

Use good variable and method names. Break code up into meaningful pieces that accomplish specific purposes. Keep your classes cohesive (it all works together) and decoupled (there are few dependencies between classes). Don't repeat yourself (DRY). Follow Uncle Bob's SOLID principles (not laws, as he points out) to the degree that they work to make the code better.

Answer 4

Self-documenting code is:

• Good naming conventions
• Clear design and separation of responsibility between components (class, function, etc.)

Remember, though, that even the most self documenting code can only ever document what's there; never what was intentionally left out, optimized away, tried and discarded, etc. You'll always have some need for English, basically, in your source files, or you're bound to leave out important caveats and design decisions.

Answer 5

The book clean code from 'uncle bob' gives you a pretty good overview of how functions should look like, with hands-on examples.

Some important points:

• small functions, classes
• good, meaningfull, names, the size doesn't matter but should be exactly as long as needed
• vertical spacing between functions/variables should be low (declare stuff as close as possible to where it is first used)
• functions and classes should do one thing and one thing only

The book has many more little rules, I really recommend it. Also get Code Complete 2.

Answer 6

Stick with the paradigm used within the environment you're coding.

An obvious example is using Pascal case for methods in .NET, camel case in Java.

Less obvious examples relate to using the same conventions as those used in the standard class library.

There's a lot to be said for this goal. Naming conventions convey a lot of information for humans, and very little for the compiler. Anyone who has consumed an API in one environment that uses the conventions of another environment has noticed how much the alien code stands out.

Consistency is a valuable characteristic that reduces cognitive load for a human consumer of code.

Answer 7

Check out Jeff Atwood's Code Smells blog post. It pretty much sums it up. I'll add my personal ethos when it comes to good readable code:

• Consistency: this applies to formatting, using braces, naming (variables, classes, methods) and directory layout (if you bury a source directory somewhere under /css I'm coming after you with a machete);
• Size: if a function doesn't fit in its entirety on the screen in a normal IDE at a normal font size then you need a pretty darn good reason as to why not. Of course there are some valid cases for much longer functions but they are greatly outweighed by the egregious examples. Decompose as necessary to keep your functions simple;
• Comment Judiciously: there is a tendency for some programmers to use comments as a substitute for readable code or to simply comment for the sake of commenting (like /* finished */ comments right before return true;. Seriously, what's the point? Most (good) code explains itself;
• Never Cut and Paste Within a Project: it's perfectly acceptable to take a code snippet from one project to another (every project is an island) but you should never take a non-trivial code segment from within one project to some other point within the project. Inevitably one changes and you leave some poor developer with the task of looking at these two or more code segments trying to work out how (and arguably more importantly, why) they are different; and
• Avoid Repetitive Code: if you find yourself writing the same sequence of statements (or very similar) over and over again, abstract or parameterize it. If you see very similar statements the tendency is to skim over them assuming they're all the same (when typically they won't be in a way that matters).

Answer 8

I generally don't comment inside code, however I completely disagree with the frequently held view that one should just write readable code and then you don't need documentation.

What I do think should be documented is your interface. By that I mean there should be comments above classes and methods. Not simple methods like set and get of course.

People who use classes and methods written by you should not have to read your code to understand how to use them. So I think one should document what legal input and output ranges are as well as important invariants. E.g. a function takes a pointer as an argument. No matter how well you name your function it can never be obvious whether supplying NULL is valid or whether NULL is a valid returned result. Often -1 and 0 are used to signal some something like object searched for not found or similar. That should be documented.

Apart from that I think the key about documenting code is not to document what a class or method does or is, but what the intention behind it is.

Answer 9

Eschew codejunk.

Edward Tufte has this beautiful, powerful concept of chartjunk, visual elements in a chart that contribute noise rather than information. By thinking about charts this way, we make much clearer charts.

I think that the same kind of thinking, applied to code, brings us much cleaner code. Examples include /* getFoo() gets the foo */ -style comments, unnecessary parentheses and braces, excessively-specific variable names, and Hungarian notation warts.

What constitutes chartjunk depends on the team, the environment, and the project - some folks like warts; some environments render code in ways that render certain junk useful (think brace-matching and // end for comments, for instance); some projects require more extensive commenting to conform with standards or to comprehensively document an API. But when a team has established standards of what chartjunk means for its projects, many decisions get easier, and its code becomes more consistent and more readable.