Comments

When programming, one of the things teachers always tell their students is the importance of commenting what you are doing. Some people would get utterly pissed for losing points for not commenting enough a script that was otherwise perfectly functional. As I only had a few scripting classes as part of the game design curriculum, I didn't realized the importance of those couple lines until now.

Designing in UO is very different than other games I've been on. Here we're jacks of all trades. We do world building, designing, decorating, storytelling and a heck of a lot of scripting. In fact close to 3/4 of our work is writing code. Problem is, this isn't like a console game where you normally have the engineers assigned to handle all the coding on specific levels and where once the game ships, that's it nobody messes with the code anymore (aside from a possible patch or two). In a MMO, and especially UO, it's not because you worked on this code today that someone else won't be using it next week or in 5 months from now. And as new content gets added or modified, properly commenting scripts takes a whole new meaning.

Ten months ago (dang has it really been that long?!) when I started on the UO team, I didn't have a whole lot of scripting experience. So this has definitely been quite a learning process. As such, I relied heavily on the work of my predecessors not only as inspiration but also as an educational tool. It's not just about how they did it, but often why they did it this way instead of that way.

What would really make me cry is opening a script with 1500 lines of code, not a single comment, funky variable names that mean nothing and function names that are even more meaningless. I will have to leave my opinion about naming conventions to another post, because I have quite a bit to say about that!

Luckily for me, there were also quite a few scripts that were little gems of comments. "This function does this". "I've handled it this way instead of that way (which would have seemingly been the logical way) because (insert reason here)". Or simple things like "this script is being attached to (...) by (...) and does (...)". And "I'm returning an integer instead of the object because (...)" or "I've added this block here to deal with an exploit where players (...)". Yes, this last part I've seen in plenty of scripts!!!

You cannot begin to imagine how invaluable those little comments are even for yourself. I go back on some of the earlier scripts I wrote and if not for my own comments I would be asking myself why the heck I did it this way. It saves so much time to not just sit there trying to figure out the logic. It can also spare others the pain you went through trying to figure out how something works next time around. By this I mean you tried to get something to work for days/weeks and finally realized that passing this type of variable will not work because the value is actually assigned elsewhere and totally bypasses what you are doing. Adding a one-liner comment saying: "note that this variable is handled by included script/function (insert name here)" will make you very popular with the next person to fiddle in this script.

On a side note, while you should always be professional in the comments you write in your scripts, some humor in good taste is never a bad idea. I like stumbling on the random comment that will make me smile, smirk or flat out lol. Speedman had a cute one that was more of a John Steinbeck wink, wink in the mace and shield glasses script where the first comment line read "Of Mace and Men". In one the Champ Spawn scripts, rather than giving one of the functions a bland "choose random players to give the scroll to", the comment was along the lines of "now the fun of picking some lucky dogs". In one of the buff scripts, the function where the buff was actually given to the player had "Beef me up, Scotty!" as a comment. Another that made me giggle (because I have a really silly sense of humor) was the "Ph4t L3wT, gImM3!gImM3!" comment where the reward was being generated on a boss monster.

In short, you should always comment your work. It shouldn't be a novel. One or two lines is usually more than plenty for a block of code. But it will do wonders for you and the people who will need to go into stuff you've done, especially if you had to handle something in a non-traditional way. The occasional smart humor is plus. Just remember that moderation is always in good taste!