FAQ Search Memberlist Usergroups
Jolt Country Forum Index
Register Profile Log in to check your private messages Log in
Log in Log in

Roody's Tips for Writing Library Contributions

 
This forum is locked: you cannot post, reply to, or edit topics.   This topic is locked: you cannot edit posts or make replies.    Jolt Country Forum Index -> Hugo's House of Horrors
View previous topic :: View next topic  
Author Message
Roody_Yogurt



Joined: 29 Apr 2002
Posts: 1993
Location: Milwaukee

PostPosted: Fri Oct 12, 2012 3:34 pm    Post subject: Roody's Tips for Writing Library Contributions Reply with quote

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:
    #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:
       case &DoGreet
       {
          print "It's unclear whom ";
          print player.name;
    #ifset _PASTTENSE_H
                if pasttense
                   print " wished";
                else
    #endif
          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).

  • 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:
    #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.
Back to top
View user's profile Send private message AIM Address
Display posts from previous:   
This forum is locked: you cannot post, reply to, or edit topics.   This topic is locked: you cannot edit posts or make replies.    Jolt Country Forum Index -> Hugo's House of Horrors All times are GMT - 7 Hours
Page 1 of 1

 
Jump to:  
You can post new topics in this forum
You can reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum


Powered by phpBB © 2001 phpBB Group

Theme by Kage Musha - RPG Garden

Copyrights and trademarks are all of the belonging company. No copyright Infringement intended