Improving Code Readability [closed]

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

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 3

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 4

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.

Answer 5

All the replies (and the question) are based on the assumption that readability is solely the responsibility of the code writer. If you don't really want to read code and you have a give up reading now list (the code smells) which matches 99% of code available and you don't actually want to even think very hard about what some code is doing, then you're not going to find any code readable.

Whatever rules we use today to make our code more readable are just going to look old fashioned and stupid in 10 years time. If you really want better code readability, read some old code (allow for the fashions of the time, that it had to run on a machine with 1000th of the speed and memory you have), make an effort to understand it and encourage someone else to do the same.

Answer 6

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