Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share

migration rejected from stackoverflow.com 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.

9 Answers 9

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.

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

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.

share
    
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

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.

share

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.

share

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

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.
share
3  
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
    
@Ergwun, updated, is that ok? –  romaninsh May 7 '11 at 15:11
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.burleson May 7 '11 at 19:38

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.

share

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:

share

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

share