So.... yeah. A voice from beyond ,"Use the Journal Luke."



-----------------------------------------------------------------------------------
I'm Kind of bored Right Now----------------------------------------------------
-----------------------------------------------------------------------------------


I've been working on sound for the game engine this last couple of weeks and finally finished things up yesterday. I ended up using OpenAL for sound and I'm fairly impressed with the ease of use of the API. The only complaint is that the documentation isn't the best for someone who is trying to get an understanding of it coming from the standpoint of a complete NOOB as far as sound went. But the tutorials on DevMaster (RIP) regarding OpenAL, coupled with the programmers reference, after a couple of solid days really dissecting everything, really helped me to get a good solid footing on using the API. I am also very satisfied with the sound classes that I ended up writing to manage everything. Essentially I just divided the sound context and listener object into one class and the source and buffer control into another. When loading a file I parse for file types and presto the appropriate logic for different formats is executed. It's very straight forward and has some nice interfaces if I do say so. This brings me to my next note.

I was recently looking over another coders code. This coder was the type of person who works alone, and doesn't use many comments. That's not a horrible practice, especially if you're dedicated and have a very intimate understanding of your code, and your interfaces are clearly named. And of course you don't expect to share it with anyone else. This on the other hand is not the case for this specific code. The interfaces were overly complex so much so that without proper documentation you would have to spend hours going through the source files to figure things out. If you have to write something more then Object->OnMoveNegx() to make an object move on the negative x plane, I think that you should definately take a look at your code. Also, if you are going to make your interfaces overly complicated and you ask someone to take a look at your code, at least have the courtesy to document the code as well as take the time to isolate an area where the problems you're having might be. If you have coded something that is giving you problems and you seriously are saying "I have no idea where the problem could be," then it's pretty obvious you've probably one either tried to do too much at once and didn't make sure that what you did worked correctly in the first place, 2 got lost in your own code because of the overly complex name schemes and interfaces, 3 didn't take the time to really understand what it was you were trying to implement in the first place and just tried to make a copy and paste Frankenstein type application.
This is some pent up stuff so I'm sorry for the long rant.

This also brings me up to what I'm currently working on, which is getting the documentation for my engine source caught back up. It's been a long while since I wrote any formal documentation and the code base has grown a lot, but my files are structured well enough that it's a fairly straight forward process to document it. The current code base is about 25,000 lines of code and 38 classes. But because of the structure of the code, it'll probably only take me 3 to 5 days to get the documents caught up, and that's only working two to four hours a day. The code itself is well commented and I believe that things are named fairly well, but the plan is that eventually others will be recruited and or hired to help with development sometime in the future. So it's better to do this as the code base grows so that when the others come, everything can be available in hard copy.

So.. I guess the lesson and theme of this post is that good documentation is important and sometimes hard to come by. It can however help to reduce the overhead with getting things going, so document your shit damnit!