Follow Slashdot stories on Twitter


Forgot your password?
Open Source Programming

Ask Slashdot: How To Start Reading Other's Code? 254 254

BorgeStrand writes "I'm reviving an open source project and need to read up on a lot of existing code written by others. What are your tricks for quickly getting to grips with code written by others? The project is written in C++ using several APIs which are unknown to me. I know embedded C pretty well, so both the syntax, the APIs and the general functionality are things I wish to explore before I can contribute to the project."
This discussion has been archived. No new comments can be posted.

Ask Slashdot: How To Start Reading Other's Code?

Comments Filter:
  • Test and Break (Score:4, Insightful)

    by Jacky Alciné (2953293) on Sunday June 16, 2013 @04:27PM (#44023571)
    If there's a lot of documentation, interpret it like your favorite religious text. Try to hit up some of the old developers from the VCS. Also, I'd like to help :)
  • by Beryllium Sphere(tm) (193358) on Sunday June 16, 2013 @04:30PM (#44023587) Homepage Journal

    Knowing the data structures gives you the ground work for understanding what the code is doing. The data structures are a more direct description of the design decisions.

  • How to read code (Score:5, Insightful)

    by girlintraining (1395911) on Sunday June 16, 2013 @04:30PM (#44023595)

    What are your tricks for quickly getting to grips with code written by others?

    For me, it comes down to a lot of mountain dew, techno music, and hours of guru meditation. As you dissect each function, sketch out its relationship to other major functions. I take a two pass approach .. first, just look at the function call outs and the return values and make a rough sketch of the 'scaffolding' of a program. On the second pass, any function that you can't see the obvious application of, or appears obfusciated or complicated, dissect into functional units and sketch out what it does in your notes. I do this by actually physically drawing the relationships using something called a mind map.

    Until you get used to it, actually writing it down, even if it's just a bunch of messy arrows to blobs of circled text... it will help job your memory and help things sink in until you have the necessary 'ah ha!' moment.


  • by zieroh (307208) on Sunday June 16, 2013 @04:42PM (#44023675)

    I find that going through some key functions (assuming you can find them) and reformatting them to your own liking can be helpful, commenting code along the way. Then if you want to get more aggressive, start cleaning up some code in minor ways that still stay true to the function's meaning. After you've done a bit of that, you should probably have at least a vague idea what's going on.

  • by girlintraining (1395911) on Sunday June 16, 2013 @04:43PM (#44023683)

    Knowing the data structures gives you the ground work for understanding what the code is doing. The data structures are a more direct description of the design decisions.

    This approach assumes the programmer hasn't gone native. Great for managed code, but when the data structures are basically pointers being passed back and forth and calls to APIs deep in the guts of the OS... well, how do I put this: You're screwed. It's a crap shoot on if the programmer even knows why it works... sometimes in C++ you stop debugging the moment it starts returning sane outputs and consider yourself lucky you didn't have to fully grok wtf just happened. :/

  • Bug hunting (Score:4, Insightful)

    by tinkerghost (944862) on Sunday June 16, 2013 @04:55PM (#44023755) Homepage
    I recommend starting by working on the bug list. It gives you something to work on constructively and it also makes you look through all the code to track the problem.
  • by benjfowler (239527) on Sunday June 16, 2013 @04:57PM (#44023761)

    The trouble with university education, is that most people who teach there are computer scientists, not software engineers with years of experience in the trenches.

    If this were actually the case, there would be a recognition that reading code is far harder than writing it. And far more emphasis would be on coming to grips, understanding, and working on large code bases. There'd be more stuff on things like unit testing, breaking dependencies, troubleshooting, and refactoring at least.

  • by spasm (79260) on Sunday June 16, 2013 @05:00PM (#44023775) Homepage

    Find out what drugs the original coder was using when writing, and take the same.

  • C vs C++ (Score:5, Insightful)

    by Rob the Bold (788862) on Sunday June 16, 2013 @05:01PM (#44023785)

    You mentioned you have embedded C experience and the code of interest is written in C++. You didn't mention if you had any C++ or other object-oriented programming experience. I assume the C++ code uses the OO features of C++ that distinguish it from C -- but this assumption is not necessarily true.

    So, if you lack OO experience and the code is truly OO C++ code, you might want to do a little reading up on the basics of OOP in order to spend less time spinning your wheels.

  • by Greyfox (87712) on Sunday June 16, 2013 @05:14PM (#44023859) Homepage Journal
    1) Just because your predecessor was paid to program doesn't mean he craps daisies and unicorns. I have often gone in with the assumption that the guy before me knew what he was doing. Quite often I find I was wrong.

    2) Just because the code is awful doesn't mean it has no value -- No matter how bad it is and how difficult it is to read, if it works at all it has probably got years (maybe even decades) of bug fixes and feature requests. Until you have a handle on it, any little change could cause a catastrophic cascade of side-effects.

    3) No, we don't need to rewrite it. See 2. A working program now is worth more than all the pie in the sky you can promise a year from now.

    4) It takes 6 months to have a reasonably good grasp of any moderately complex in-house application. It could be a year before you get to the point where someone can describe a problem and you immediately have a good idea of where in the code the problem is occurring and what functions to check.

    Maintenance programming is as much about detective work as anything else. The only clues you have about the previous programmer are his source files. Once you've read them for a while you can start to tell what he was thinking, when he was confused, when he was in a hurry. Most of the atrocious in-house applications have changed hands several times and each programmer adds their own layer of crap. You can redesign these applications a chunk at a time until nothing remains of the original code if it's really bad, but it's best to save really ambitious projects until you understand the code better. I heartily encourage the wholesale replacement of "system()" calls with better code immediately, though. In several languages I've run across these calls to remove files, when they could have simply called a language library call (Typically "unlink".) If the original programmer used system("rm...") you can pretty much assume that they were a bad programmer and you're in for a lot of "fun" maintaining their code.

  • make it move (Score:5, Insightful)

    by superwiz (655733) on Sunday June 16, 2013 @06:15PM (#44024197) Journal
    It's just how your brain works. It's a lot easier to examine a piece of mechanical machinery when it's in motion. You notice more. Do the same with the code. Run it. Run components independently. Put plenty of log statements or if it's feasible, watch under a debugger. But don't try to look at stale code just sitting there. You'll notice more as it moves.
  • Re:Unit Tests (Score:0, Insightful)

    by Anonymous Coward on Sunday June 16, 2013 @06:44PM (#44024433)

    Mod parent down.

    If you don't "understand" code, in this context this means you don't know what its good for (what requirements it fulfils), but only what it does (which is the information you're getting from reading the code). Therefore, it's impossible to write any test-case for it, except one that verifies that it does what it does. And that's pretty useless, unless your plan is to test the compiler.

  • by Java Pimp (98454) < minus berry> on Sunday June 16, 2013 @07:18PM (#44024613) Homepage
    You will never fully understand the code just by reading it. My approach is to ignore all of it until something needs to be changed. When you need to change something, add a feature, etc... find where in the code the functionality is and tweak it a bit. See what happens. Tweak it some more. See what breaks. You will start to get a deep understanding of a focused section of the code and not have to worry (yet) about other unrelated areas. Start with small changes first. Larger changes may require a deeper understanding of the architecture and how pieces interact. This will come in time. After a few iterations of this and you will eventually become intimately familiar with all the pieces of the code.
  • by shess (31691) on Sunday June 16, 2013 @07:32PM (#44024679) Homepage

    Spend an afternoon or three skimming around the code pulling threads and following them. Jump around kind of randomly, if things start making sense in one module, go somewhere else for awhile. Take frequent breaks. Take notes about what you think things are doing, or perhaps ideas about how to improve the code - but don't start improving things now, you just want to figure out how much you're in for.

    After awhile doing that, you should have a few ideas about good accomplishable problems, now pick one and go deep for a limited time (hour, afternoon, week, depends on the scope of the code and your commitment to it). Again, keep notes, and then throw all your work away (or check it in somewhere - but don't focus on shipping, that detracts from learning). Again, go somewhere else in the code, fix something, take notes, throw it away. Alternate back and forth between research and application, trying not to bias towards one or the other (which can be a form of procrastination).

    Now throw away all your notes. They were written by someone who had no idea what was going on. By now you're pretty sure you know what's going on (you don't) and how to make things better (you have no idea), so circle around for another pass. Stop when you start finding that your notes seem to be recognizing actual immediately-actionable problems and solutions, rather than hypothesis and speculation. Or just stop because you're now so busy fixing things that you don't have time for exploration.

  • Find the author (Score:4, Insightful)

    by Antique Geekmeister (740220) on Sunday June 16, 2013 @07:51PM (#44024795)

    Find the person who wrote the code. Make sure that educating you or your colleagues is part of their paid responsibilities, and make sure that you respect their work when reviewing it: this helps them share the ir work and take it well if you need to revise things. My colleagues and I often bring new features or help stabilize old projects, and a working relationship with the original author is invaluable.

    And ff the author says "just read the code, I don't do documentation because documentation can lie", or if they say "don't bother checking the data for correctness, just don't make mistakes", be ready to throw out _everything_ they ever wrote. It may work at the moment, but it's likely to be as broken and unsustainable as their attitudes.

  • by Zalbik (308903) on Sunday June 16, 2013 @07:57PM (#44024827)

    he trouble with university education, is that most people who teach there are computer scientists, not software engineers with years of experience in the trenches.

    Exactly. And it's why I always encourage programmers to write for readability rather than for terseness or whatever the latest cool tool is. Code is also read many more times that it is written.

    I'd much rather see a procedure that takes 10 lines is immediately obvious what it does than an "optimized" 5 line procedure that takes some head scratching to figure out.

    People who claim "more lines of code mean more probability of error" are typically very wrong. .

  • by ranton (36917) on Sunday June 16, 2013 @08:56PM (#44025077)

    Honestly, I wouldn't get too comfortable with a given IDE -- some of them (I'm looking at you, Visual Studio) abstract away and hide a lot of the code and it can make for some really confusing times for you.

    Honestly, I would take more time to get comfortable with a given IDE so you can actually use it well instead of feebly. A good IDE like Visual Studio rarely abstracts away anything that you aren't trying to abstract away. And since most of the time you want almost every part of your program to be abstracted away from you, ,which is most of the power of a good IDE, this is what makes an IDE so useful.

    Not being competent with a good IDE is far worse than not completely grepping your coding environment at a low level. At least in today's world (I had a different opionion 15 years ago). Google and coworkers can fill in a lot of gaps in knowledge when necessary, but spending day in day out using an IDE and never realizing how much better it is than command line tools is a big waste of productivity.

  • Re:Unit Tests (Score:5, Insightful)

    by skids (119237) on Sunday June 16, 2013 @09:12PM (#44025149) Homepage

    This. Looking at existing tests is also very educational. They often show where the codebase was confusing enough to cause recurring regressions.

    The other place to make very, very sure to read is the repository commit logs, if you have them. They'll tell you a lot about why the code is in its current state, and will often show you where refactors have been left half-complete.

  • Re:Unit Tests (Score:5, Insightful)

    by gd2shoe (747932) on Sunday June 16, 2013 @09:28PM (#44025211) Journal

    No, unit tests are a good idea. They wouldn't be my first choice, but they're a good option when deciphering a particularly difficult project.

    (1) It gets you to interact with the code. This is always a good idea when leaning how something behaves. Fiddle with it for a while and see if you can figure it out.

    (2) The unit tests don't need to be particularly true to their original requirements to be useful. When you do eventually start making changes, the law-of-unintended-consequences comes into play. If you make a change and one of your unit tests starts failing, then it will give you a clue that things may be interacting in a way that you did not anticipate.

"Virtual" means never knowing where your next byte is coming from.