Lately I have used a programming convention of defining some "sections" within the code of a verb. This is just a convention which seemed to be a good way to keep certain meta-information about a verb within that verb, so that other programmers or maybe some automatic processing could find it. For instance, the web-interface to viewing lily code is smart enough to use a special format when displaying the changelog section.

Right now, all these sections are put in the source code for the verb, after the statements you really want to execute. An unconditional 'return' statement is always placed before all the lines for any section in the verb, so my hope is that these sections will not slow down the normal execution of the verb. NOTE that I might be wrong about that, in which case we'll have to store the sections somewhere else (perhaps in a companion-verb?), and make the @program and @list commands smart enough to keep the real verb and the "somewhere else" in sync as changes are made. I'd like to avoid that, though. The present tactic seems simple enough to maintain.

Each section is indicated by a starting and ending marker. That marker looks enough like a valid executable command that the language-parser does not flag an error, but you'll get an error if the statement is actually executed. The starting markers are of the form: '---[section_name];' , and the ending marker is always of the form '---[end];' .

So far, I have come up with three different section names: changelog rationale snippets

So, for instance, you might see a verb which has the following lines at the end of it:

    return 1;
    " -------+---------+---------+---------+---------+---------+---------+----*";
    ______[changelog];
    " 2005/11/23 gad ";
    " - fix the return value for a few cases (mainly the case where we were ";
    "   given a list of discussions, none of which the user is ignored in). ";
    " - allow 'unignore public' to clear out the list of all discussions ";
    "   being ignored, even if the user has not done a '/ignore other public' ";
    "   to ignore the other-user in *all* public discussions. ";
    "";
    " 2000/12/07 ratlifc ";
    " - added return to indicate actual change (PR#123) ";
    ______[end];
    .

In the case of the changelog section, there is also a specific format that I'm trying to follow for each entry in the changelog. Note that by moving all these changelog entries to the end of the verb, you won't see them when you do @howto verbname . The @howto command also works on a programming convention that lily developers started to follow, of putting comments at the start of a verb which described the MOO calling-sequence for that verb. But then we also put "last change notes" in the same comments. If you tried to do a @howto on some verbs, you'd get 4 lines of information about the calling sequence for that verb, followed by 40 lines of change-log information!

I will probably define another code-section specific to those how-to comments, and then change the @howto variable to print out that section, of it exists. Of course, we have so many verbs now that it's a bit tedious to make a change like that across all verbs at once, so I just make the changes to verbs whenever I have to change them for some other reason.

I will have to write some more on this at a later time...

-- GaranceDrosehn - 29 Nov 2005
to top