Joined: 29 Apr 2002
|Posted: Fri Oct 12, 2012 3:34 pm Post subject: Roody's Tips for Writing Library Contributions
|I think most Hugo authors appreciate a good library extension. In the process of writing my own, I’ve picked up some tips which I’d going to pass on here. More suggestions will be added to this thread as I think of them.
- Make it easy to include
First off, you want to make sure the contribution is easy to throw into other people’s games. If your contribution is a simple thing like an object class, even a simple .txt file with just the object code is fine (the expectation being that authors will just copy and paste the code into their games). For larger contributions, you’ll want to give your header file (.h, .hug) a distinctive name and bookend your code with something like this:
< entire library contribution >
This accomplishes a couple different things. It allows other extensions (and your game code) to check if your extension has been included, and it also disallows your code from being accidentally included twice.
What you don’t want to do
If possible, you don’t want to distribute your code solely as an example game where authors have to spend a fair amount of time modifying it to meet their own needs.
Separate response text into message routines
If you look at Hugo library files, you’ll notice that messages are usually contained in routines devoted to them. Separating messages from the game actions they are associated with make it easy to change a response without changing functionality (or conversely, changing how things work without changing the message).
Likewise, your library contribution should have its own message-distribution routines, set up for easy replacing. This will allow other authors to easily stylize contributions to match the tone of their games.
Check out this page for info on how to make message routines: http://hugo.gerynarsabode.org/index.php?title=Messages
Name your message routines after your contribution (example: FootnoteMessage, FootnoteNewMessages) so they don’t interfere with already-existing message routines. We can’t have a dozen extensions fighting over verblib.h’s VMessage.
Not all messages have to be redirected this way, of course. Some routines only exist to print out a short message, like the verbstub verb routines. As these can be easily replaced using the ‘replace’ function, it’s not necessary to do anything fancy with them.
make messages non-player specific (past tense optional, too)
If the scope of your library contribution is large enough, you may want to write your responses in a way that they’ll work with games not written in the second person. To do this, take a look at similar code in hugolib and verblib and see how they use IsorAre and MatchPlural. Example:
| case &DoGreet
print "It's unclear whom ";
print " wished";
MatchPlural(player, "wishes", "wish")
" to greet."
You’ll see that the above example also works with the “pasttense” extension (not that past tense is common among Hugo games).
Of course, you’ll want to explain your contribution as well as possible. Comment your code and provide documentation where possible. An included example game doesn’t hurt, either.
organize your routines
It is sometimes helpful to group similar routines together, like hugolib replacement routines, verb routines, or general utility routines. This makes it easier for a newcomer to see how an extension deviates from standard library behavior and such.
give your contribution release numbers
Especially if your contribution is a work in progress, it's very important to keep track of version numbers. I like to write version numbers a couple different places in my extensions as a reminder to keep them updated. I even add this code to my extensions so I get a message at compile-time about what version contribution is being used:
#message "NewConverse.h Version 1.9"
Keeping a changlog with your contribution can also be helpful.
be mindful of how your contribution will interact with other existing extensions
If your extension's behavior might break other extensions, in the least, it is worth pointing out in your documentation. It may be also possible to finesse your code so it plays nicer with other code.
Well, that's what I've got so far.