Tips for Writing Readable Code

If debugging is the process of removing software bugs, then programming must be the process of putting them in.

E. W. Dijkstra

Before you code

• Data Structures are more important than the code, think about them first.

• Keep It Simple and Stupid. It will be more robust.

• Write what you know of the problem as comments

• Break the problem into steps, put them in comments

• Learn from others, look at how others solved it, from internet, friends. (Don’t Copy)

• Be ready to rewrite your code till you are happy with it.

Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it.

Brian Kernighan

Functions

• Keep it as small as possible

• Small functions are reusable

• They are easier to understand

• Helps in breaking down the problem

• Small depends on the problem, but on an average functions should not be more than 50 lines.

• Functions with Switch Case statements are special

• Use inline, if number of calls is a concern, and the function is small

Naming

• Be very careful with naming

• Good naming replaces comments

• Let your names tell the story

• Keep local names short; global names long.

• Underscores are more readable than Capitalization

• Don’t be afraid of renaming, as long as others don’t use them.

You should name a variable using the same care with which you name a first-born child.

James O. Coplien

Indentation

• Always indent your code

• It is very important for readability

• Use large indent levels, 4 is minimum, 8 is better

• More than 4 indentation levels in a function indicates bad code; split or rewrite

Variables

• Keep the number of variables in a function small

• Create structures where ever grouping is possible.

• Too many variables may indicate the need to split function

• Too many variables makes it difficult to follow what is being done

• Define variables where you need them.

Check for failures first

• Reduces need for indentation levels

• Prevents use of flag variables

• Makes code easier to understand

• Use return if nothing needs to be done

• Use goto or a do while(0) block if several things are required to be done before return

Comments

• Comments should never be about what your code does; that is what code is for

• Comments should be about what the code should do.

• Explain complicated piece of code; explaining why the complication was required.

• Function headers should give the rationale for the function, and input/output parameters.

• Do not put redundant information in comments

Logging

• Be ready for testing.

• Think which errors are likely to happen

• Put logs when important data gets modified

• Have some sanity logs.

• Entry and exit logs are useful.

• Logs should always contain some data to print.

• Use appropriate levels for logs

• Let the log system worry about keeping the logs to a minimum.

Warnings

• Warnings indicate errors.

• Use –Wall and remove the warnings.

• Preferably use Lint and static code checkers if available.

• It is best to discover as many potential bugs as possible.

Code Duplication

• Copy Paste although easy, is evil

• If you are copying a piece of code, find out a way to do it another way, and reuse the code

• Small functions help a lot.

• New bugs surface in old code, due to changing environment, host.

• Duplicate code, duplicates bugs, requiring multiple discoveries of the same bug

Code Density

• Make each line of code matter

• Putting more code in fewer lines helps view more code at once.

• Don’t put every opening brace on a new line

• Function opening brace is special

• If a ‘if/while/for’ statement fits on a line, no need to have a block.

• But if it takes more than one line, then use a block.

• You do not need an ‘else’ if the ‘then’ part returns from the function.

Change to Understand

• Change code that you do not understand

• Understand code that you are about to change

• Code must change to suite the developer.

• Code that cannot change is difficult to maintain.