Please share experience on how to make the source code easy for other to follow?

Question

I can write source code in a period of time, but after a while of not touching the project, it takes me time to be familiar with the source code again. Also, other people need some time to study the program...

How do you make source code more easy for others to follow?

Answer 1

A few tips:

• Keep your code simple (the KISS principle) - favor clarity over performance in algorithm choice unless you know that part of your code is performance critical.
• Separate responsibilities appropriately between classes (assuming your code is OO) and methods.
• Choose meaningful class, method and variable names.
• Comment the "why": write comments to explain why your code does what it does, not just say what it does - your code already says what it does.
• Follow a consistent coding style.

Answer 2

Others have suggested some books. These are a couple others with many of the answers you seek, in order:

1. Code Complete by Steve McConnell
2. The Pragmatic Programmer by Andrew Hunt.
3. Refactoring by Martin Fowler and Kent Beck
4. Design Patterns by Eric Gamma et al.

The readability of your code will improve as you advance through each of the books, guaranteed.

Answer 3

Read Robert C. Martin's Clean Code and learn the SOLID principles.

Read Eric Evans Domain Driven Design book.

Be very picky about naming. Modularize by functional cohesion.

Write a small wiki page about the system does. Give some background into the design, give an overview of the key components in the system and how they relate. Keep it short so people feel inclined to keep it up to date. Let newcomers update the page when they find a mismatch between the documentation and what the system actually does.

Be very conservative with comments, they easily end up only adding to the confusion. Put as much explanation into language constructs, this keeps your code refactor friendly. Introduce concepts if it makes your code communicate it's intent better.

Answer 4

Have a peer review your code with the mindset "I - and only I - am the next maintainer of this code!".

This will cause them to ask many questions in order to understand what goes on. Those questions and their answers need to be incorporated in the code+comments, so the next reader thinking the same questions can find the answer immediately.

Answer 5

While there are a multitude of techniques and heuristics to help you do so, I think it boils down to making the code read as close to english (or your group's native language) as possible. My usual process is to actually write it in plain english comments first, then go back sentence by sentence and transcribe it into a programming language statement that resembles the english statement as closely as possible, deleting the comment.

For example:

// Use pythagorean theorem to find the hypotenuse from the lengths of both sides

becomes:

float hypotenuse = pythagorean(length_side1, length_side2);

Obviously then, you go back and define pythagorean, length_side1, and length_side2 in similarly readable terms.

This might seem like a trivial example that is difficult to get wrong, but what happens when people are writing it is that the definitions are more fresh in their minds, and they are writing it one word at a time anyway, so they substitute the more complex definitions because it seems more efficient at the time, leaving something like this:

float hypotenuse = math.sqrt((triangle.point[1].x - triangle.point[2].x)^2 +
    (triangle.point[1].y - triangle.point[0].y)^2);

Then they will reread the above to themselves, realize it's not immediately apparent what's being done, and feel compelled to insert a comment. Try to transcribe the code into english, and you'll see why because it comes out something like this:

The hypotenuse is the square root of sum of the square of the difference between the x coordinates of points 1 and 2 of the triangle and the square of the difference between the y coordinates of points 0 and 1 of the triangle.

Technically, that's valid english, but no one can understand you without a lot of effort. Being able to write code that reads like clear english is one reason I feel computer science college students shouldn't begrudge their english composition and other liberal studies courses.

Answer 6

The top rules are simple:

1. Keep the code self-documented (meaningful variable names, separated logically).
2. Employ best practices (so no one thinks "what the hell is this?" when looks at something aimed at eg. replacing Model-View-Controller architecture).
3. Document! Use Javadoc, PHP Doc (http://www.phpdoc.org/) or solution for your language and do not even think about not documenting something.
4. Document your code also in the places that a while is needed to read the expression to determine what it does and what is its purpose.

Answer 7

OP have asked how to make source code easy to follow. While comments help, code is a code. Consider this example (PHP):

$form=$page->add('MVCForm');
$form->setModel('Employee',array('name','salary'));
if($form->isSubmitted()){
    $form->update();
    $form->js()->univ()
        ->successMessage('Employee added')
        ->execute();
}

Even though it has no comments, it's very clear what this code does. First it adds a Form and sets model Employee for the two fields of name and salary. If form is submitted, then it's data should be updated in the database. Afterwards JavaScript will be used to show success message.

The code above is from example on this page. Main principles behind the code:

• keep it compact and very readable. Show it to people who don't know about your code or even don't know about programming. Ask them what they think code does.
• pick a language which offers sufficient amount of syntactic features to structure code nicely. If you are writing in C, it might not be possible to have code easy to read and perform well.
• think objects. MVC is just one case of object structure. Go beyond that. How about using View(Form) with Model(Employee) directly?
• keep comments short. If your code is readable, then add comments only when needed. But they are still important. Long comments often make code less readable because of gaps.

Answer 8

Comment every non-trivial line/function

Have an architecture document of the software handy & updated

For your own reference, have a class architecture diagram regenerated every time you make major source changes. You could look into doxygen, I have found it pretty useful.

Other than that the very fact that you are asking something like this makes you a good developer, and a good person to work with.

Answer 9

Spartan Programming

In my experience, the best way to make code easier to follow is to make it more succinct and readable, and you can achieve this with is with Spartan Programming, here is some material to read:

• Coding Horror: Spartan Programming
• Code Reduction or Spartan Programming
• Spartan Programming

Answer 10

Always code and document as if you'll be leaving in a month and the person replacing you will be a fresh graduate who has never seen the code base before.

This might sound over the top. But in my experience, the time "wasted" on the most long-winded way to do things properly doesn't come anywhere near close to the price you pay later for technical debt.

Basically, whenever you find yourself thinking "this should be obvious enough to leave undocumented/uncommented" or "this is simple enough to remember", it isn't. Eventually those five "saved" minutes will turn into a whole wasted day, or worse. Either yours or someone else's (who inherits your code base).

Answer 11

In a word: Humor. Yes, you should pick meaningful variable names, but if you can make them funny as well then reading the source code is fun and much easier to do. Open the employee file to a variable named "The.Downtrodden.Masses". Spit out a report to the printer with a function named "Ptui". My favorite is when you need to say something to the user and wait for a keypress to continue. You don't care what they enter, you'll never use that variable again after the input statement, so take the time to tell a one-liner about a co-worker (Ira.eats.pork, or Diane.is.a.cheeto.addict). I once loaded a few variables with data and got to write "Open(the.pod.bay.doors, hal) else print (Im.Sorry.Dave, Im.Afraid.I.Cant.Do.That). Your code will compile down to the same size with longer names as it would for shorter ones, and the end-users will never see the names you choose, so have fun with it.