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.

Almost every advanced programmer says that it's very useful to read the code of other professionals. Usually they advice open source.

Do you read it or not? If you do, how often and what's the procedure of reading the code? Also, it's a bit difficult for newbies to deal with SVN - a bunches of files. What's the solution?

share|improve this question
add comment

8 Answers 8

up vote 22 down vote accepted

Do you read it or not?

Yes.

If you do, how often

Daily. Constantly. I work with numerous open-source projects (mostly Python-related) and must read the source because it's the most accurate documentation.

and what's the procedure of reading the code?

Um. Open and Read.

Also, it's a bit difficult for newbies to deal with SVN - a bunches of files. What's the solution?

Open and Read. Then read more.

It's not easy. Nothing makes it easy. There's no Royal Road to understanding. It takes work.

share|improve this answer
    
Thanks for you answer. What is the way of defining whether the code is good or not? Because not every open source project is done by real professionals? –  Sergey Apr 20 '11 at 12:12
1  
@Sergey: "What is the way of defining whether the code is good or not?" Read the code. "Good" is subjective. If it's helpful, and you can understand it, it's good. If it's confusing, or doesn't actually work, it's not good. There are many, many quality attributes: maintainable, secure, adaptable, high-performance, etc., etc., etc., code can be good at one and less good at another. –  S.Lott Apr 20 '11 at 12:15
6  
I couldn't resist: osnews.com/images/comics/wtfm.jpg –  Gary Willoughby Apr 20 '11 at 12:37
    
@Sergey - even if it is the greatest code ever written, if you can't read it (because of your level of experience), it won't do you any good. Although you may see it as not the best use of your time, you're going to get exposed to poorly written code, so you might as well learn the difference. Like S.Lott said, it takes work and time. –  JeffO Apr 20 '11 at 13:41
    
While I admire those who can sit back and read code like they read a novel, I find it a bit tedious at times. I have realized that for me ‘reading code’ does not really describe the activities that I undertake – a better phrase for what I do is ‘code comprehension’ and it involves reading documentation, stepping through it in a debugger and even reading the tests. I wrote a long post about code reading - technikhil.wordpress.com/2010/07/06/how-to-read-code-a-primer –  Nikhil Mar 3 '12 at 4:34
add comment

There's several layers to the conundrum you have. First, start at the high level, a birds-eye view so to speak. Once you check out a project there will be a bunch of files in a directory structure. That's the same whether you are looking at open source or closed source (source code is source code after all). So start with this:

  • How are the source files organized? Can you tell by the name of the file or the name of the containing directory what you might find inside? We programmers tend to like predictable names and logical structure. You should be able to get a rough idea of where to look on a specific problem.
  • What's the nature of the application, is it web based, command-line, GUI? The reason this is important is that you want to know where to start tracing the execution. If it's web based you want to start with where the app starts processing the request. If it's built on a framework, all the better. Once you know the framework you can usually make good sense of the code that is there. Otherwise you will be starting with the respective entry point for the command line/GUI app.
  • Get a sheet of paper and a pencil, or if you are lucky a whiteboard and dry-erase markers. Give the components names (or use the ones provided in the code) and draw lines between the boxes with arrows so that you can see how things are processed. Alternatively, if you are looking at an algorithm, sketch out the data structures in a way you can understand and sketch out how it is manipulated.

It takes practice, but it is definitely doable. The more you know about the libraries and frameworks the application is using, the more you know how the code needs to be organized and where to look for answers to specific questions. Some code is a little harder to follow, particularly if it is fairly indirect. That's why you need the pencil and paper. Eventually a light bulb goes off in your head and you get it. That's when reading the rest of the code makes a whole lot more sense.

share|improve this answer
    
One aspect of reading code is abstraction. Things such as finding out how sources are organized will definitely abstract the process of code reading. –  David Gao Aug 10 '13 at 3:11
add comment

One trick I use quite often when reading some complicated function, code segment is to start refactoring it into something more readable without changing the logic.

share|improve this answer
1  
+1: Me too. // I once had a boss who noticed the refactoring and accused me of wasting time. He couldn't understand. What a fool. –  Jim G. Apr 20 '11 at 13:25
add comment

It's not reading like you read a novel, but more like how you read a reference book. A good way is to pick a recently fixed bug from a check in message, do a diff of what changed, and read the relevant parts until you understand both the problem and the solution. Well-publicized security vulnerabilities are fun bugs to pick because there is a lot of discussion about them on the forums. Then pick one of the "low hanging fruit" bugs from the bug tracker and read until you understand how to fix it yourself. Most of the code reading professionals do is incidental in the course of fixing bugs or adding features.

Usually the best code samples are barely noticeable. You will instantly understand them without reading through them more than once. They make it look like it was extremely easy to write, even though code that good usually goes through many drafts. It produces the paradoxical feeling that of course the given code is the obvious way to do it, even though it's not the first way you thought of.

When you come across code like that, try to understand the insight that went into writing it, and the design principles involved, so when you find yourself in a similar situation in the future you can hopefully apply the same principles.

share|improve this answer
add comment

How is having to deal with "a bunch of files" hard? It's no different from when you write your own code, except you don't have prior knowledge of its organisation unless it's documented.

If you, as a claimed programmer, can't figure out the project structure from "a bunch of files" either it's an extremely poorly organised project, or you're an inept programmer (or, in extreme cases, both).

Start reading, try to find some entry points or otherwise essential pivot classes/methods, and build an understanding of how it all comes together from there. Won't be instant, will take time, but can be done even if there's no documentation at all.

share|improve this answer
3  
"Will take time" to "build an understanding" is pretty much the definition of "hard." Just because it's a difficulty we are expected to deal with every day doesn't make it less difficult. "Where do I make this change?" is a common question even among professionals. Also, source control and dealing with large code bases is one of the huge holes in college educations. I think I did one or two projects in college that required more than one source file, and they only got up to around 10 files. –  Karl Bielefeldt Apr 20 '11 at 13:18
add comment

if you want a deeper reference, you might want to check this book out.

Covers probably everything you want to know and more :)

share|improve this answer
add comment

The best thing you can hope for when reading the code of another project, be it an API or piece of software is that the variables, functions and macro names aren't abbreviated ambiguously or named so that you can figure out their intent.

But other than that, it takes a decent amount of knowledge spread across language, programming techniques and also about the code's purpose itself to be able to dive into complex code.

I'm currently trying to see how Lua does some of it's magic, but I'm getting to the point above where a lot of the identifiers are named vaguely and rather abbreviated to the point where I can't figure out which line is trying to do the thing I know has to be done at some point in the function code... The frequent single letter variables and rather abbreviated macro/function names are doing my head in.

share|improve this answer
add comment

After looking at the "First, start at the high level, a birds-eye view" as @Berin Loritsch sugested you can look for unittests and/or integrationtests if there are any.

unittests are interesting to see how (api-)details work.

integrationtest usually give a good overview over businesprocesses.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.