Friday, September 18, 2009

Rigs Of Rods - understanding a new codebase

Before to get into some coding, I'm trying to get an overview of RoR's codebase. Unfortunately it's not very clean. No big deal, I created monsters worst that this... But really, trying to figure out what does a function of thousand lines called frameStarted is depressing. I would have like they took time to split what can be.. Sub-functions, sub-classes and packages not only give a felling of order, but also help comprehension.

Indeed, when you arrive in a project which is already well advanced, get some understanding of how the stuff works is the first thing to do. If someone, say Robert, is here to explain it to you, it is somehow easy. Robert will sit on a chair next to you and go straight to key classes, gives you a little sentence explaining what each class or function is supposed to do and how they are related to other classes.

If the project is big, he will skip what doesn't interest you, eventually tell you that you don't have to understand this or that to accomplish your task.

On a well structured code, the brain will classify everything in little boxes saying: this is a class for handling the terrain, this class I don't care for now, classes in this package are about physics, etc.

Alright, but when nobody is there to explain? Well, that is what comments are about, they need to replace Robert, give a picture of what is the code does. That is why all classes should at least have a little explanation that can be read by someone who doesn't know much about the code.

I can give an illustration, taken from a exam revision program I wrote:

// A file where answers are stored (with compression)
class AnswerArchive;

There it is. It's a nice comments that probably says enough for a man that already knows about the project internal details. But doesn't give the class reason of existence in the big picture, so it's little help for newcomers.

Let's try again.

// Overview:
// Answers given by the user needs to be stored to allow review of previous exams later in time.
// - the ExamReview class loads data from an AnswerArchive for this purpose.
// - the ExamState class appends given answers to the AnswerArchive at the end of a session.
// Compression is applied to the data, because the mobile version have a low storage capacity.

// A file where answers are stored (with compression).
class AnswerArchive;

Now we know who uses this class and why it exists. Because what it does is not the only thing one would like to know about a class or function, why it does it also is important.

Well, I really wish RoR developers took time to do it. They didn't so I think I'll better try to find some "Robert" in forum!

1 comment:

  1. Hello Jeko :)

    You answered my message on this forum.

    How may I contact you to discuss?

    Thanks !

    Best Regards,