Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

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?


migration rejected from Dec 3 '13 at 0:04

This question came from our site for professional and enthusiast programmers. Votes, comments, and answers are locked due to the question being closed here, but it may be eligible for editing and reopening on the site where it originated.

closed as primarily opinion-based by gnat, GlenH7, MichaelT, Robert Harvey, Dan Pichelman Dec 3 '13 at 0:04

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise.If this question can be reworded to fit the rules in the help center, please edit the question.

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.

+1 for these resources. These books helped me much to improve myself. – Md. Mahbubur R. Aaman Feb 5 '13 at 6:29

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.


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.

FYI. I didn't add the books you suggest to my list because I haven't read them. – Apalala May 8 '11 at 22:42

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


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.


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

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('Form');
$form->setModel('Employee', ['name','salary']);

    if ($form['salary'] < 100) {
        return $form->displayError('salary', 'Too little');
    return 'Employee added';

And see it in action here:

Even though it has no comments, it's very clear what this code does. As a designer of Agile Toolkit framework I have spent a lot of time trying to remove any unnecessary constructs, characters or methods and teach users to write clear code.

Here are some of the principles I follow as framework developer:

  • keep all methods compact and readable, developers must love their code.
  • pick a language which offers sufficient amount of syntactic features, but use them to simplify usage.
  • think objects. Chaining calls is a great way to shorten code.
  • teach framework concepts and code culture to your developers.
  • readable code beats comments.
  • follow coding standards and outline your code nicely with logical spacings.

p.s. I have updated the code to conform with recent framework version and removed univ() method (read more here if you are interested about univ()).

what does ->js()->univ() mean? – user1249 May 7 '11 at 13:45
The OP actually asked about "how to make [...] source code easy for other to follow?". In this context, 'follow' can be taken to mean 'understand' rather than just 'read'. Comments are relevant. – Ergwun May 7 '11 at 15:07
js() method returns a JavaScript class which is tied to selected object. Any further calls are converted into jQuery-ui, so the above code would produce $('#id_of_form').univ().successMessage('Employee added'); where univ() is a standard jQuery plugin. – romaninsh May 7 '11 at 15:09
I don't think it's clear at all. What's $f? What's $p? What's update() updating? Is all this just boilerplate PHP that I would know about if I were a PHP programmer? – kirk.burleson May 7 '11 at 19:38
The code is understandable now. I had a look at this answer's revision history and I'm not sure if it was meant to be a joke: "f" and "p" are pretty poor variable names. – Sedate Alien May 9 '11 at 3:34

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.


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:


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