• entries
152
85
• views
99314

DYSD!

314 views

So.... yeah. A voice from beyond ,"Use the Journal Luke."
 So...yeah.             So...yeah.   So  .  .             . yeah .    S     o    . . .     Y      eahHum..                          Hum..     .      +          +     .    .      ( )        ( )     .   .                            .   \                            /    .                          .     \                        /       |       \     /       |        \                   /         |                 |          \               /           _______________

-----------------------------------------------------------------------------------
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!

Working on a public facing API has made me shore up my documentation standards; I do big doxygen-style comments with integrated "running commentary" comments as the function proceeds when necessary.

Aye, back in high school I did some minor coding for this startup networking company my dad joined. They wanted me to make heads and tails out of some networking code left behind by two outsourced people that had left the company. There were like, no comments. None. In fact there were so few that I still believe to this day that the two coders intentionally removed them all and were laughing at me the whole time. Bastards.

Commenting/documenting is good, despite what some people may say (ahhh, memories...)

Ravuya: Very Cool! I'd never heard of doxygen before. It looks very promising for documenting purposes and looks like it'd save a lot of time. Thanks for that example and suggestion.

Gaiiden : If I had to go through that experience, I would probably have found another job. I would rather start a project over from scratch then to have to track down all the code. Still, a funny image of those guys going through and erasing all the comments.