Roody's Tips for Writing Library Contributions

Roody_Yogurt · Post by **Roody_Yogurt** » Fri Oct 12, 2012 3:34 pm

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:
Code: Select all
```
#ifclear _LIBRARYNAME_H
#set _LIBRARYNAME_H
< entire library contribution >
#endif
```
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:
Code: Select all
```
	case &DoGreet
	&#123;
		print "It's unclear whom ";
		print player.name;
#ifset _PASTTENSE_H
				if pasttense
					print " wished";
				else
#endif
		MatchPlural&#40;player, "wishes", "wish"&#41;
		" to greet."
	&#125;
```
You’ll see that the above example also works with the “pasttense” extension (not that past tense is common among Hugo games).
good documentation

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:
Code: Select all
```
#ifset VERSIONS
#message "NewConverse.h Version 1.9"
#endif
```
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.