Sunday, July 25, 2004

What does that "R" stand for?

Documentation should never take a backseat no matter what the reason. How much easier would the life of a programmer be if this was the mantra of all programmers, including themselves?

It's been almost 2 months since I did any serious work on Sydney. I made the decision to shelve it temporarily to let me focus on finishing up at my day job. Once I left the day job I was kept busy servicing other business clients and organising the home computer help business.

This week though, I have very little on my plate and will be devoting the time almost entirely to recommencing the development of Sydney. That is once I work out what I was doing 2 months ago. I've spent a few hours this weekend looking at my code and although I think it's good, there's definitely room for improvement in the developer documentation area.

I guess the fact that I was squeezing it in before going off to my day job provided me with an excuse to not follow my own documentation standards quite so closely. Sydney currently consists of quite a few class hierachies and seperate projects. Individual classes and methods are reasonably well commented but their interactions are not. I'm having to relearn the structure of the program by stepping through the system in the debugger. Luckily I do have a reasonably good suite of unit tests which illustrate the most external interfaces of the system, leaving me to rediscover only the internal interfaces.

It looks like the first two or three days of this week need to be devoted to properly documenting the existing code base. Nothing too flash, some hand drawn sequence diagrams and a few more class diagrams will probably suffice. At the end of the week if I've got some time on my hands I might transfer a few of the most relevant ones to Modelmaker or Visio.

What about the mystery "R" I hear you say. The "R" in question formed part of the name of each of the seperate project executables. The project executables of which there are many currently all have acronyms for names that describe their function. For the life of me though I could not remember what R stood for in these acronyms. I even went so far as to go to the dictionary and start reading through the R's to try and jog my memory.

Of course it came to me when I least expected it. The "R" stands for RemObjects which is the remoting library that Sydney currently uses. It's included in the name in case I ever get so far as to implement a "D" version (DCOM) or a "C" version (CORBA).

Naming conventions are no good unless you can remember what they are. Documenting that project naming convention will be number one on the list for tomorrow, as long as I remember what "R" stands for come the morning.

0 Comments:

Post a Comment

<< Home