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

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.

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.

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.

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.

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:

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.

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.

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.
–
ErgwunMay 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.
–
romaninshMay 7 '11 at 15:09

1

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.burlesonMay 7 '11 at 19:38

1

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 AlienMay 9 '11 at 3:34

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