Script Module Guidelines discussion

Started by RickJ, Wed 02/02/2005 03:01:21

Previous topic - Next topic

RickJ

(Edit by strazer: Thread was split, don't be confused.)

Module Programming Conventions
I had a go at documenting the conclusions reached in the discussion below.  I will update these as the discussion progresses. 

  • Module Programming Guidlines
  • Module Script Template
  • Module Header Template



    Here are some questions that came to mind during development of the IniFile module.  Let me know your thoughts or perhaps you may have other questions.   

    Documentation
    I embedded tutorial and reference docuemnts in the header file because I thought that, that documentation should always stay with the module and a seperate/external file wouldn't be as tightly bound as  the header would be.  However, after finishing the documentation, it seems to me that it is too large to be embedded in the header and that this would probably be generally true for most all modules (unless of course the author neglected to produce any documentation).   Ok, so then where should the documentation reside, if not in the header file?  External txt file?   Should we ask CJ to add a text document to the module mechanism?  What other alternatives are there?   

    Programming Conventions
    What programming conventions do we need to recommend so that modules from multiple authors and times can be used together in the same game.  For example inIniFile the module name is used to define a struct (i.e. OO Object) and to prefix #define definitions to ensure these definitions would be unique and not interfere with other modules.   So if there is only one module named IniFile imported into the game there shouldn't be a problem. 
       struct IniFile {
          :
       }
    
       #define INIFILE_BUFSIZE 500
          :
    

    So what other, if any, conventions are necessary to avoid such incompatibilities?   

    Publishing, Licensing, etc
    I think we should recommend some publishing guidelines to make the module feature as useful as possible for as many people as possible.   Should it be native scm format or compressed into zip.  If the latter what other, if any, files should be included in the zip.  What kind of license should we recommend?   I used GPL for the time being for lack of better ideas.   Probably we could come up with something the is much briefer and serves the purpose of giving people permission to use the module in their games.   Any ideas?    I think also we should recommend which "permissions" should be enabled in the Module Manager.   These recommendations would of course be for module authors wishing to publish their work for use by the AGS community.  If someone had a reason to do something different they could elect to do so.   Such recommendations would be a common starting point for all and would encourage consistency.   What should be recommended?

    Announcing, Reviewing, Release Module List
    How should new modules be announced and reviewed?  Should this be done in the AGS forums, if so which one(s)?  Where can we keep a list of released modules - maybe a sticky or somewhere else?

    Edit 2006-04-27:

    A short summary of the guidelines can now be found here.

strazer

#1
Here are my thoughts:

Documentation

I prefer external text files. It's easier to have them in a seperate window if you quickly need to look something up while having the script editor open.

Programming Conventions

Yes, a prefix should definitely be used. I also think adding a (maybe abbreviated) prefix to function names would help grouping related functions for the auto-complete feature.

Publishing, Licensing, etc

I think we should use zip files, containing the scm file, documentation and optionally a simple demo game.
At these small file sizes the superior compression ratio of rar or ace is insignificant.
Zip files are easiest to access on all platforms.

I don't know what specific license to suggest, but the module author should definitely write something in the docs. Is it free for non-commercial AND commercial use? Is a credit required or optional?

As for module manager permissions, I will release my modules with all permissions granted. The beauty of modules is that you can customize them to your needs, so it should be possible to do so.

If you want users to credit you for your work, just say so and I'm sure most people will be happy to do so.

Announcing, Reviewing, Release Module List

I was wondering about that myself.
I think they should be announced and debugged in the Technical Forum, then moved to the Technical Archives just as Tools and Plugins are now.

SSH

Quote from: RickJ on Wed 02/02/2005 03:01:21
Documentation
I embedded tutorial and reference docuemnts in the header file because I thought that, that documentation should always stay with the module and a seperate/external file wouldn't be as tightly bound as  the header would be.  However, after finishing the documentation, it seems to me that it is too large to be embedded in the header and that this would probably be generally true for most all modules (unless of course the author neglected to produce any documentation).   Ok, so then where should the documentation reside, if not in the header file?  External txt file?   Should we ask CJ to add a text document to the module mechanism?  What other alternatives are there?   

Here are some possibilities:

POD: Perl's Plain Old Documentation system is great: There is dosucmewntation embedded ina  code and there is also a standard pretty printer that lets you read it in  a nicely formatted way, like a UNIX man page

HTML: Some peopel might want pictures, etc. in their documentation

MIME: maybe there's a way for a generic MIME encoded document to be attatched and then AGS opens it with your default web browser,  like an email attatchement might?
12

Scorpiorus

#3
Documentation
I agree about having an external file with full doc on the module and, perhaps, a brief info in the header itself. I think we should consider a format of an external file.

Programming Conventions
Having a module name prefix is definitely worth it. A think maybe general purpose functions could be made static and thus grouped together.
By the way, should 'defines' be like:
INIFILE_BUFSIZE
or
IniFile_BUFSIZE (to be consistent with a module prefix)
or?


I thought about providing two versions of a module. One that can be modified and the other is a safe one - that can't. For example, if somebody want to use a module functionality but don't intend to modify anything it would be reasonable to use a safe version of the module to avoid occasional changes of its code. Also, if an imported module is changed for some reason (because it's allowed or due to an error compiler detected) it would be nice if such module were marked (with an asterix or anything) that it was changed. This is important I think, since the module author can't really support it (answering a topic posted or somehow else) if module content isn't original anymore. Then one can be suggested to use an official copy of the module to see if it fixes a problem. And indeed if editing of a module information isn't allowed but its script can be changed then one may end up using "original" module (looking at the module info) but in reality the script is completely different.

Pumaman

Good work, Rick :)

In terms of the license, I wouldn't recommend using the GPL. It effectively means that anyone using your module has to make their entire game open-source, which most people wouldn't want to do.

You might want to look at the LGPL (Library GPL) which is based on the GPL but designed for add-on libraries.


Also, I think this would be a good time for me to clarify the permissions system. Firstly, the permissions are NOT intended to be any sort of security to stop people accessing your scripts. If you disallow script access, but a compile error occurs, the user will be able to edit it to correct the problem. Similarly, the scripts are not encrypted on disk and it wouldn't be hard for the user to read them.

The permissions come into effect when you export a module. The original game in which the module was created always has full permissions over it, but if you import the module into another game then the restrictions come into force.

I wouldn't recommend that people disallow script and header access to the module as a general principle.
The more useful feature is disabling editing module information, so that your author and version information remains intact.

RickJ

#5
Publishing, Licensing
Quote
In terms of the license, I wouldn't recommend using the GPL. It effectively means that anyone using your module has to make their entire game open-source ...
Yeah, I this was the last thing I added to the document and was just to tired to think about it very deeply.  I started reading through LGPL and just glazed over.  Seems that both of them have a lot of stuff that just doesn't apply. 

Perhaps we should just compose a simple paragraph that clearly states what is expected?  The problem with this, is that it would be uncertain how well such a thing would meet any kind of legal standard.  However, isn't this the case with the AGS license itself?  If so, then I suppose we just do something similar for modules.

Has anyone ever come across the creative ecommons license?  I like their approach, they allow you to select the terms you desire and then they generate a license for you.  You can try it here: http://creativecommons.org/license/

You end up getting something like this: http://creativecommons.org/licenses/by-sa/2.0/

Well, I like to know what everyone thinks about this...

Quote
I thought about providing two versions of a module. One that can be modified and the other is a safe one - that can't. ...
I'm not sure this is necessary in light of your next point ...

Quote
Also, if an imported module is changed for some reason (because it's allowed or due to an error compiler detected) it would be nice if such module were marked (with an asterix or anything) that it was changed. This is important I think ...
which I also think is very important.   The real problem is that one person modifies a module and then passes it on to another person.  The other person is unaware of the modifications and has problems becsause of them and asks the author for help.  I think a way of permantly marking modules so modified is absolutely necessary.   Shall we make some kind of feature request?

Quote
I think we should use zip files, containing the scm file, documentation and optionally a simple demo game.  At these small file sizes the superior compression ratio of rar or ace is insignificant.  Zip files are easiest to access on all platforms.
Yeah, I agree with this.  I wonder if the demo game should be a seperate download though?  The module files are so small in comparison.

Documentation
The concensus seems to be that an external document, combined in a zip package is the desired module delivery format.  The reasoning for this is that an external document can be viewed independently of (simultaneously with) the AGS Editor session.   

The problem I see with manually creating and maintaining an external document is that it will either not get done or not stay up to date.   So I looked into document generator thingies such as the one SSH suggests.   The problem with most of them is that JRE, Perl, Python, or whatever needs to be installed (IMHO not everyone would be willing to do this) and/or that it would take a lot of hacking to get them to work with AGS. 

I have been tinkering around to see how feasible it would be to make an AGS document generator, capable of extracting comments and some statements, such as function definitions, etc, to rendering plain text, html, and sgml documents.  It seems to me not too difficult a problem.  So far I've written parser primatives capable of extracting and intepreting individual lines of text comments in a format similar to the ones in the IniFile module.   Form the expermenting I hav been doing I think it would be possible and feasible to ...
  • Generate a document directly from a SCM file.
  • Generate a document directly from a TXT file.
  • Interpret natural looking text
  • Interpret key script statements
  • Control what is and is not included in the document
  • Automatically generate table of contents (with hyper-links)
  • Output document to TXT, HTML, SGML
  • Perhaps at some point provide capability of documenting an entire game from a text dump.

    I wonder what everyone else thinks about this idea?   If there are reasons to take another approach or better alternatives I''d like to discuss them.  If not I'd like to go forward  with my idea. 

    Quote
    I agree about having an external file with full doc on the module and, perhaps, a brief info in the header itself. I think we should consider a format of an external file.
    What do you mean by "format"; file type, document structure, or aestethic appearance? 

    File Type - My three file type candidates are Plain TXT, HTML, and DocBook/SGML.   

    Document Structure -  I'll prepare an outline roughly based on the IniFile documentation and post a link to it, so that can use this as a starting point for a discussion.  If someone else would like to create an outline then please volunteer.

    Aestethic Appearance - I guess we can comment on this as we go through the process.

    Programming Conventions
    Quote
    Having a module name prefix is definitely worth it. A think maybe general purpose functions could be made static and thus grouped together.
    By the way, should 'defines' be like: INIFILE_BUFSIZE or IniFile_BUFSIZE ...
    I think the module name should be unique in a case insensitive manner so that upper-case, lower-case, and mixed-case versions of the module name can be used as prefixes.  I used "#define INIFILE_BUFSIZE..." because #defines are normally in all caps.  On the other hand the alternative "#define IniFile_BUFSIZE" appeals to my sense of simplicity/consistency (i.e. don't need as many prefixing rules).  I wonder what the others think? 

    Quote
    Yes, a prefix should definitely be used. I also think adding a (maybe abbreviated) prefix to function names would help grouping related functions for the auto-complete feature.
    I am not sure exactly what you mean by abbreviated prefix?   Do you mean an abbreviation of the module name or additional abbreviations, such as "DelSection(), DelOption(), DelValue()" to control the list order in the auto complete.   I think abbreviating the module name increases the possibility of name collisions.

    Announcing, Reviewing, Release Module List
    Quote
    You might want to look at the LGPL (Library GPL) which is based on the GPL but designed for add-on libraries.
    I guess this is probably the one to recommend.  Any other ideas???

    Quote
    I think they should be announced and debugged in the Technical Forum, then moved to the Technical Archives just as Tools and Plugins are now.
    Sounds like a plan.  Any other opinions, ideas?

    Thanks for your inputs.  Let me know what you think about an AGS document generator. 

    Cheers

strazer

#6
Quote from: RickJ on Wed 02/02/2005 22:44:43
Quote
Yes, a prefix should definitely be used. I also think adding a (maybe abbreviated) prefix to function names would help grouping related functions for the auto-complete feature.
I am not sure exactly what you mean by abbreviated prefix?   Do you mean an abbreviation of the module name or additional abbreviations, such as "DelSection(), DelOption(), DelValue()" to control the list order in the auto complete.   I think abbreviating the module name increases the possibility of name collisions.

Yeah, I was thinking of INI_DoStuff(), but you're right that it could easily cause name collisions.
Static functions grouped together by the full module name is probably the best approach, i.e.

Code: ags

struct IniFile {
  import static function SomeStuff();
  import static function SomeOtherStuff();
};


Quote from: RickJ on Wed 02/02/2005 22:44:43
I wonder if the demo game should be a seperate download though?  The module files are so small in comparison.

I for one will put it into the package. It depends on the size of the demo but the default game is so small, a few kilobytes more don't matter to most people. It's up to the module author, really.

As for documentation, everyone has their own idea of what it should look like.
I say keep it simple, just put up a few recommendations of what a proper doc should contain and the file format (TXT or HTML) and let's leave it at that. Anything else is a waste of time IMHO. The programming conventions part is far more important.

Scorpiorus

#7
Quote from: RickJ on Wed 02/02/2005 22:44:43
QuoteI agree about having an external file with full doc on the module and, perhaps, a brief info in the header itself. I think we should consider a format of an external file.
What do you mean by "format"; file type, document structure, or aestethic appearance?
Sorry for my previous miserly input on the issue and yeah I was meaning the format in general, including file type, doc structure etc.
Anyway, I really like the idea with the document generator to automatize the doc-creation process. Personally, I don't see any disadvantages with such approach as it serves the same purpose as modules themselves, that is for the structurization, which in turn simplifies the management of the whole system. So, it's just a matter of creating the doc generator which is not an easy task I appreciate, and I'm looking forward to finally see it in action. And I would be glad to help with anything I can.

Quote from: RickJ on Wed 02/02/2005 22:44:43
Quote
I thought about providing two versions of a module. One that can be modified and the other is a safe one - that can't. ...
I'm not sure this is necessary in light of your next point ...
I agree that marking a changed module would be enough, but on the other hand completely restricting of editing its code would also decrease the possibility of occasional changes and thus the possibility that somebody even had a problem. What I don't like about the safe-version approach is that:

a) we'd need two versions involved;
b) there is no normal way to look into the source script code without downloading an editable version;

Would be cool if there were an option to only read the code but not edit it. It could still be possible to unlock it by clearing a tick in the module properties. So it's mainly to disable editing by default.

For example, I have a script that's a candidate to be incorporated into a module but the script requires a user to write some event-handling functions. I though about separating these event functions into another module -- thus I have two modules. I'd like to make the main module be a read-only so that one have no chance to edit it by mistake while intending to edit the event-handling part which is to be edited.

RickJ

#8
Documentation
Quote
As for documentation, everyone has their own idea of what it should look like.
I say keep it simple, just put up a few recommendations of what a proper doc should contain and the file format (TXT or HTML) and let's leave it at that. Anything else is a waste of time IMHO. ...

Quote
Anyway, I really like the idea with the document generator to automatize the doc-creation process. Personally, I don't see any disadvantages with such approach as it serves the same purpose as modules themselves, that is for the structurization, which in turn simplifies the management of the whole system. So, it's just a matter of creating the doc generator which is not an easy task I appreciate, and I'm looking forward to finally see it in action. And I would be glad to help with anything I can.
I agree whole heartedly about keeping things simple, because if it's too complicated then it won't get done.  One the other hand a document generator offers numerous advantages but adds a bit of complexity (at least initially) to the process of authoring a module.  It would appear however that the bigest  percieved downside of a document generator seems to be the effort in implementing it.

I propose that we take both Scrop's and Strazer's suggestions.  First we come up with a simple document format that can be easily done manually in txt and html.   Then we make a document generator that can produce same from source code.  In this way if the doc generator is too much for some one to deal with they can just do it manually.  For those who prefer a document generator they can have their preference as well. 

I believe I have gotten through the most difficult part of doing the document generator.   At this point I am not intending to do any kind of in depth code analysis so as to document completely undocumented code as some commercial and/or deluxe document generators do.  The goal is to extract information from resonably documented code and render it into a document.   

I am the point where I can start generating output.  Any inputs about the document format, contents, structure, etc would  be most helpful.  Here is a proposed list of sections I think should be included in the document.  Have I left anything out or included too much?  Which should be main sections and which should be sub-sections?
  • Title - module name, author, version, etc. 
  • Abstract - paragraph briefly describing module's functionality
  • Contents - table of contents (hyper-linked if html)
  • Description - description of how to use the module
  • Definitions - #define constants, enum values, and data types defined in header
  • Globals - global variables and global functions
  • Object-1 - properties and functions
      :
  • Object-n - properties and functions
  • License
    Here is the current text version of the IniFile documentation.  Feel free to comment or post format modifications. [edit]****updated document below ****[/edit]
    http://www.gaia-spa.com/project/ags/modules/manual.txt

    Programming Conventions
    Quote
    The programming conventions part is far more important...
    Agree, very important.  Perhaps there should be "Script Module Guidelines" or similar document that contains this and other info?   What do you think?  How should we proceed?   

    Here is a document I recently produced  describing the conventions I use when writing AGS script language.    Hehe, I was planning on asking you guys to review it, then the new module stuff made it out of date.  Anyway if this is the kind of thing you are thinking about I would be happy to take a shot at doing something similar for modules. 
    http://www.gaia-spa.com/project/ags/doc/ProgrammingConventions_V002.txt

    Publishing
    Quote
    I for one will put it into the package. It depends on the size of the demo but the default game is so small, a few kilobytes more don't matter to most people. It's up to the module author, really.
    Yeah, I can see the advantages of including it.  I guess that's what I would want if I were trying to use someone else's module for the first time.   

    Quote
    Would be cool if there were an option to only read the code but not edit it. It could still be possible to unlock it by clearing a tick in the module properties. So it's mainly to disable editing by default.
    Maybe edit should be disabled automatically when ever a module is imported.  Then as you suggest anyone can enable editing via a check box.   Then if changes are made there would need to be some way of permantly marking the module as changed from the original.  It would be cool if the module manager maintained a permenant revision history.  Perhaps if a module was imported, modified, then exported, the user would be prompted for name, and a 1 sentence summary of changes.  If that copy were then distributed it wouldn't be confused with the original.


Scorpiorus

#9
Documentation

Quote from: RickJAny inputs about the document format, contents, structure, etc would  be most helpful.  Here is a proposed list of sections I think should be included in the document.  Have I left anything out or included too much?  Which should be main sections and which should be sub-sections?
First of all great work on both the IniFile manual and the AGS script programming conventions!

I like the overall layout of the IniFile doc which seems very practical and also meets the basic requirements of the international standart on the documentation of that kind, that's nice and I believe each section has its right place.

And what do you think if the "Definitions", "Globals" and "Object-XXX" sections would be put as subsections of a module structure (or whatever it should be named) section as follows:


  • Title
  • Abstract
  • Contents
  • Description
  • Module structure
                    Definitions
                    Globals
                    Object-1
                    :
                    Object-n
  • Revision History
  • License

What I mean is that although in most cases objects are standalone entities, they can have some complex connections with each other, be nested etc. AGS currently doesn't support nesting of structs but who knows what may come in future. So, by introducing such section we can abstract from module's internal structure.

I also think that we should refrain from using the "object" word but use "instance" and "struct" as much as possible to avoid possible confusion.

What do you think if a function prototype declaration would precede its description; taking the IniFile function description, for example:

Code: ags

5.6 IniFile.GetInt

function GetInt(string section, string option, int default=0)

   Description:
   This function gets the specified option value from the data buffer,
   If the option is found the value is converted to an integer and 
   returned.  If the value is not a number then a value of zero is 
   returned. If the specified option is not found then value specified 
   by the DEFAULT parameter is returned.

   Return Values:
   value - Integer value of option or zero

   Example:
   IniFile Config;               
   int num_errors;               
   Config.ReadFile("test.cfg");  
   num_errors = Config.GetInt("Code Statistics", "errors");

   Sets num_errors equal to the integer value of the "errors" option.


That's because the description refers parameters of a function and thus, I think, they should be mentioned before as a part of function's head for consistency.


Programming Conventions

Yeah, programming conventions is an important thing but what I think we should consider in a first place is a module naming and interoperating conventions, since any given module may be regarded as a black box with an internal structure we don't (or do :)) care of. Anyway, if we are after using the module functionality in our own module (i.e. we're not after editing that serving module) what we need is an interface to interoperate. The recent beta of AGS introduced the #error directive (thanks Chris!) so along with a help of the other directives we can connect two different modules.

Here is an example of the script (Module2 depends on Module1):

Module 1

Header:
Code: ags

// check for interfering:
#ifdef MODULE_Module1
#error Module with the same name already exists!
#endif

// registering this module:
#define MODULE_Module1


Script:
Code: ags
//doesn't depend on anything



Module 2

Header:
Code: ags

// check for interfering:
#ifdef MODULE_Module2
#error Module with the same name already exists!
#endif

// registering this module:
#define MODULE_Module2


Script:
Code: ags

// checking if the necessary module exists with aborting compiling if it doesn't:
#ifndef MODULE_Module1
#error Can't find the required module!
#endif


Alternatively, we can allow compilation to proceed and go ahead replace serving module functionality throughout the code. Some kind of warning to report would be nice here though.

What I mainly wanted to discuss is how we should name our module internally so that that name can be check from within other modules if necessary.

It is clear that the name should contain module's prefix (inteface struct name) but it must additionaly include something else, otherwise module's name would interfere with struct's name.

Here is some conventions I thought of:

  • IniFile (not the best as it may interfere with other module global names, but in fact it is possible to deal with that; autocomplete feature may suffer though I can guess)
  • MODULE_IniFile (the format I used in the script example above)
  • IniFile_ (taking into account the underscore character can be used for macros, enums)
    Other module name suggestions?
    Or maybe the module name should additionally contain version number like:
    MODULE_IniFile_V100 (good for making compiling decisions)
    and(or)
    #define MODULE_IniFile 100 (value can be used at run time)


    As for module (prefix) naming I think mix-cased names are ok, so far we have:

    IniFile.member
    IniFile_MACRO
    IniFile_SomeGlobalFunctionThatWasn'tMadeStaticForSomeReason
    IniFile_enums


    QuoteWould be cool if there were an option to only read the code but not edit it. It could still be possible to unlock it by clearing a tick in the module properties. So it's mainly to disable editing by default.
    QuoteMaybe edit should be disabled automatically when ever a module is imported.
    On the other hand, some modules (like such contaning event functions to adjust) should be editable (by default at least). But yeah, I like the idea for the modules author to specify what module can be edited by default and what can't be. But the checkbox can actually be ticked/unticked as one may need.
    Revision history thingy would also be neat, I agree.

    :)

RickJ

Documentation
Quote from: Scorpiorus
I like the overall layout of the IniFile doc which seems very practical and also meets the basic requirements of the international standart on the documentation of that kind, that's nice and I believe each section has its right place.

And what do you think if the "Definitions", "Globals" and "Object-XXX" sections would be put as subsections of a module structure (or whatever it should be named) ...
Yeah, I was thinking the same thing.  I started out with a flat document structure but have since realized there is a need for sub-sections.  I couldn't think of a good name for "Module Structure" either.   For a section name, I was thinking along the lines of the following but couldn't make up my mind:

  • Reference
  • API Reference
  • Script Reference
  • Module Reference
  • API
  • Scripting or Script

    and of course your suggestion

  • Module Structure

    So yes I agree with your suggestion about Module Structure, we now just need to pick a name for it, which I guess is of secondary importance. 

    Quote from: Scorpiorus
    I also think that we should refrain from using the "object" word but use "instance" and "struct" as much as possible to avoid possible confusion.
    I know, but I knew to whom I was speaking.  I wanted to make a distinction, for the purposes of this discussion, between structs defined in the header and that have methods from those defined in the script.  I think the former needs to be in the document while the latter does not.   And of course, in the end the document will refer to IniFile rather than Object-1.  Still you make a good point and perhaps we should try  to get in this habit.

    Quote from: Scorpiorus
    What do you think if a function prototype declaration would precede its description; taking the IniFile function description...
    Yeah, that's probably the right way to do it.  I was thinking the same thing and was surprised that I hadn't already done so in the example document.  I guess I thought about this after I did the original document and didn't think about it when I did the most recent update.   I was planning on the document generator doing it this way.  I was even thinking that the HTML version could encclose the declaration in a box and use a different font,color, etc for the declaration.  I was thinking of doing the same or similar thing for all entities in the Module Structure section.

    Programming Conventions

    Quote from: Scorpiorus
    Yeah, programming conventions is an important thing but what I think we should consider in a first place is a module naming and interoperating conventions, since any given module may be regarded as a black box with an internal structure we don't (or do :)) care of...
    Agree with all ..

    Quote from: Scorpiorus
    Alternatively, we can allow compilation to proceed and go ahead replace serving module functionality throughout the code. Some kind of warning to report would be nice here though.
    Hehe, I asked CJ about this in the beta thread and he said that the compiler
    doesn't support warnings.  So I didn't press any further.  Maybe once we finish our efforts here and have something to show, we can present him with a "list of our demands" ;)

    Quote from: Scorpiorus
    What I mainly wanted to discuss is how we should name our module internally so that that name can be check from within other modules if necessary....
    I guess I would reject the following ones; "IniFile:  because of the reason you mention, "IniFIle_" because it looks like an incomplete macro definition and could be easily deleted or inadvertently created. 
  • IniFile_
  • IniFile

    This one kind of looks ugly, but I am thinking this may be a good thing ;) because it is very easy to notice.  I suppose you rejected  IniFile_MODULE because of the possibility that the module designer would want/need to use that name for something, which I would agree with.
  • MODULE_IniFile

    The only other variation on name is to just use a leading underscore to identify system or required macros (i.e. used for compilation, etc and not for module functionality). 
  • _IniFile_V100
  • _IniFile

    I like the idea of including version numbers but how would you implement a  "V1.00 or higher" requirement?.    Would we need to include a macro for each major version like this?
    #define  _IniFile 200
    #define  _IniFile_V200
    #define  _IniFile_V100

    Quote from: Scorpiorus
    As for module (prefix) naming I think mix-cased names are ok, so far we have:
    IniFile.member
    IniFile_MACRO
    IniFile_SomeGlobalFunctionThatWasn'tMadeStaticForSomeReason
    IniFile_enums
    What about global variables?
    IniFile_GlobalVariable

    What do you mean by "ThatWasn'tMadeStaticForSomeReason"?  Why not just
    global functions.
    IniFile_SomeGlobalFunctionThatWasn'tMadeStaticForSomeReason

    Is there a difference between the type name and value definitions? 
    IniFile_enums

    Also I am unclear about enum value name collisions.  If two different enum types are defined can they have the same value names.  For example, does the following work?
    enum TypeA {
       Paper.
       Scissors,
       Rock
    };
    
    enum TypeB {
       Rock,
       HardPlace
    };
    ===
    Another thing I think we need to discuss regarding programmng conventions is what should be in the header and what should be in the script.  Normally in AGS, most people put all of their macro definitions, etc in the Script Header.  However in the case of a module only those things that are meant to have a global scope should be placed in the Module Header.  That pretty much means that everything in the Module Header should be using the module name prefix as discussed about.     I guess I am stating what is obvious to us and what is implicit in the preceeding discussion but I think this should be clearly stated in any module programmng document we produce. 

    This brings us to the next point we haven't discussed yet.  What should the naming rules be for the Module Script?  Here is what I have done so far:

  • IniFile_GlobalVariable
  • IniFile_GlobalFunction()
  • IniFile.Property
  • IniFile.Function()
  • StaticVariable - Declared outside bounds of any function
  • ApplicationFunction() - Main function, may call one or more utility function  but not other Application Functions
  • dynamic_variable - Declared within bounds of a function
  • utility_function() - Small function, may call other utility functions but not application function.

    I am not sure about naming conventions for the following Module Script items.  Should they also use the prefix or should they be forbidden from using it?  I guess my inclination is that they shouldn't use the prefix since it's not necessary.   
  • structs
  • #define
  • enum

    Scrop, would you be willing to start a text document describing the above conventions.  I am especially interested in you explaining the compilation and dependancy issues since you seem to have your head around that at the moment.   I don't understand the details, implcations, etc regarding the compilation thing as well as you do.  So I think you could explain this better than I.   I don't mind contributing, perhaps we could take turns adding stuff to the document.  What do you think?

    Publishing etc
    Quote from: Scorpiorus
    But yeah, I like the idea for the modules author to specify what module can be edited by default and what can't be. But the checkbox can actually be ticked/unticked as one may need.  Revision history thingy would also be neat, I agree.
    Then I think we should put them on our "list of demands" ;)

Scorpiorus

Documentation

QuoteYeah, I was thinking the same thing.Ã,  I started out with a flat document structure but have since realized there is a need for sub-sections.Ã,  I couldn't think of a good name for "Module Structure" either.Ã,  Ã, For a section name, I was thinking along the lines of the following but couldn't make up my mind:
Ah, I see what you mean by that names. My "module structure" suggestion seems more like it describes both the module interface as well as the internal structure of the module which, I agree, shouldn't be really mentioned (maybe it could be made an optional separate section or just additional document concerning technical details of organization of a module). I'm not sure about a proper name either. I think it should be something that makes it clear that the section contains more detailed info about the module (more deep theory) than "description" as well as API itself. Or possibly API should be made a standalone section?
Anyway, ommiting section names here and there that's what I think the high-level sections could look like:



I rely on user don't know anything about the module, so:

  • Title
    There is no problem with that, I believe. Module name should roughly tell one what the module relates to. For example, IniFile makes it clear that the module has something to do with the ini files. If one don't need such functionality but maybe looks for the string functions module there is no point to read further. Well, except maybe for the abstract section, just in case. :)

    Author name and version, etc. are also here, fine.


  • Abstract
    This paragraph should finally make it clear whether the module is what one's looking for as it describes module functionality (very briefly though, without dwelling on details).


  • Contents
    Table of contents. Also fine here.


  • ?Description?(Intro)
    I'm not sure about the name because there could be another section with the same name. Anyway, the section should tell basic theory about the module and here, what is important, one'd find examples on how to use the module (some kind of a brief tutorial). If one were presented with working examples that would encourage them to study the module API further. Of course, there is no need to list a complete list of functions and types there (just basics).
    IniFile's "Description" is a pure example of what this section should look like.

  • Description (module structure)
    Here it is. Maybe the "module structure" section should be named "description"? Anyhow, the purpose of the section is to describe the module structure in details. There is more theory and no a word about the internal structure of a module. The section should probably reference all the API functions but shouldn't provide their detailed descriptions, it should contain: "...to access the XXX feature use the YYY function..." etc. And how to use a certain function should be told in a separate section. Setting up hyperlinks could be essential feature to make referencing very easy here.

  • Reference (scripting/definitions/etc.)
    Ok, finally. This section could mainly be autogenerated. It should list all the types/globals/functions/constans etc. that can be referenced from the "Description" section as well as provide their detailed explanations. The point here is that if one understood the module structure (from the previous section) there is no need to look there all the time and the "Reference" section is exactly what one would generally want to look in.

  • Revision History

  • License



    ...Here is what I thought of. Also, there could optionally be an additional section (probably after "Reference") - "Technical details" to describe the internal structre of a module. Or possibly it should go as a standalone document or just be a part of the comments throughout the module source code?

    What are your thoughts?


    Programming Conventions

    QuoteHehe, I asked CJ about this in the beta thread and he said that the compiler
    doesn't support warnings.Ã,  So I didn't press any further.Ã,  Maybe once we finish our efforts here and have something to show, we can present him with a "list of our demands" ;).
    Yeah, I think he mentioned that's it a possiblity to introduce warnings mechanism in a future version. That would be a nice chance to also add some kind of a #warning directrive to report user-defined warnings.

    QuoteI guess I would reject the following ones; "IniFile:Ã,  because of the reason you mention, "IniFIle_" because it looks like an incomplete macro definition and could be easily deleted or inadvertently created.
    Having IniFile as a name almost works, i.e. if we define:

    #define IniFile IniFile

    Then there is no interfering but the problem is that autocomplete doesn't show up a list of static functions, i.e.

    IniFile x;
    x.

    ...works, but...

    IniFile.

    doesn't.


    I don't like IniFile_ too, what I probably meant is something like IniFile_H which is very similar to IniFile_MODULE you mentioned. And the reason I suggested MODULE_IniFile is because with MODULE_ being a prefix it would be possible to show all the modules in the autocomplete list once "MOD" is typed. :)

    QuoteThe only other variation on name is to just use a leading underscore to identify system or required macros (i.e. used for compilation, etc and not for module functionality).
    Yeah it, though, kinda restrict anyone from using leading underscore characters similar to what C does. :) So the question is, should it just be an underscore character or maybe a longer prefix like "MUDULE_" or something simiar?

    QuoteI like the idea of including version numbers but how would you implement aÃ,  "V1.00 or higher" requirement?.Ã,  Ã,  Would we need to include a macro for each major version like this?
    A bit clumsy, I agree, but that's the only way out so far. :)

    QuoteWhat about global variables?
    IniFile_GlobalVariable
    Ah yeah thanks good point, forgot about them.

    QuoteWhat do you mean by "ThatWasn'tMadeStaticForSomeReason"?Ã,  Why not just
    global functions.
    Well, that's another issue. The question is, should we made all global functions static?

    struct Lib {
    import static function Func1();
    import static function Func2();
    import static function Func3();
    };

    And always have:

    Lib.Func1();
    Lib.Func2();
    Lib.Func3();

    instead of:

    Lib_Func1();
    Lib_Func2();
    Lib_Func3();

    Even if the only purpose of a struct is to just group module global functions.

    QuoteIs there a difference between the type name and value definitions?Ã, 
    IniFile_enums
    I think enum type name is only used by the autocompleter to list related enum values. Or do you mean something else?


    QuoteAlso I am unclear about enum value name collisions.Ã,  If two different enum types are defined can they have the same value names.Ã,  For example, does the following work?
    Unfortunetly, no. They all must be unique. I think it's a good idea to use prefix for module enums that in the header:

    enum IniFile_Enum {
    IniFile_eValue1,
    IniFile_eValue2,
    IniFile_eValue3
    };

    QuoteAnother thing I think we need to discuss regarding programmng conventions is what should be in the header and what should be in the script.Ã,  Normally in AGS, most people put all of their macro definitions, etc in the Script Header.Ã,  However in the case of a module only those things that are meant to have a global scope should be placed in the Module Header.Ã,  That pretty much means that everything in the Module Header should be using the module name prefix as discussed about.
    Entirely agree.

    QuoteI guess I am stating what is obvious to us and what is implicit in the preceeding discussion but I think this should be clearly stated in any module programmng document we produce.
    Second that! That's why I mentioned about the "object" name, for instance. Just to make sure it was stated at least once! ;)

    QuoteThis brings us to the next point we haven't discussed yet.Ã,  What should the naming rules be for the Module Script?Ã,  Here is what I have done so far:
    I agree on them. Well, maybe there could be exceptions for the internal implementation of the module. One may also want to use variable names like "loopCounter" or bFlag (with b have a meaning of "bool") etc.

    QuoteI am not sure about naming conventions for the following Module Script items.Ã,  Should they also use the prefix or should they be forbidden from using it?Ã,  I guess my inclination is that they shouldn't use the prefix since it's not necessary.
    Yeah, sure there is no need to clutter up the source code with prefixes since they are not required there.

    QuoteScrop, would you be willing to start a text document describing the above conventions.Ã,  I am especially interested in you explaining the compilation and dependancy issues since you seem to have your head around that at the moment.Ã,  Ã, I don't understand the details, implcations, etc regarding the compilation thing as well as you do.Ã,  So I think you could explain this better than I.Ã,  Ã, I don't mind contributing, perhaps we could take turns adding stuff to the document.Ã,  What do you think?
    I can try at least. :) Think, yeah, I'll begin with module dependency stuff and then after it will be cleared up we can continue on other conventions. Module naming seems like the only difficult issue so far. :) Adding/editing document in turns seems to be a good idea. I also hope others will suppose ideas as well.


    p.s. Sorry I've missed something because I'd written pretty much yesterday but was unlucky (or silly...) to accidently close the window thus wipping everthing out I had on the topic.

RickJ

Documentation
Quote
... Well, except maybe for the abstract section, just in case. ...
At one point I put Title and Abstract in the same section but couldn't tihink of a good name.  I sort of made an artificial distinction because the information they contain is  in a different format.   Currently if a line begins with a title capitalized tokens terminated by a colon, it is interpreted as a form field (i.e. name, value pair).   For example "Author Name: John Smith" would be interpreted as a form field named "Author Name" having a value of "John Smith".  The idea is that subsequently in the document that something like @Author Name@ could be replaced with "John Smith".  I don't know if/how this will be used but it's a feature I would like to include.   

I guess my real point here is that if the document generator is to remain single pass then form fields will need to be defined before they are used.   The file head or Title section seems like a logical place for most of those things to appear.   The Title section can then be rendered from a template that includes only the relevant information (using the @substitute@ mechanism).   Information not relevant to title is then available for substitution through out the document.   Ok, I know that it's a feature that may not get much use but it may be something we will find a use for.

So that's the reason for having Title and Abstract in stead of just one section that includes both informations.

Quote
I'm not sure about the name because there could be another section with the same name. ...
Ok, we agree aboout the order and content here.  The author of course can add sub-sections as desired to this section.   

Quote
... Anyhow, the purpose of the section is to describe the module structure in details.  ...
Is this like a module overview/description that gives technical theory, philosphy, and details about how the module is constructed?  I originally envisioned this info as a "Introduction" sub-section at the begining of the Reference "API or whatever name we choose" section.  I see your point about making it a seperate section though and the following is probably reason to make it so.
Quote
./.. The point here is that if one understood the module structure (from the previous section) there is no need to look there all the time ...
I guess it depends on how big and complex this section ends of being.  I suppose there is no way of knowing in advance.   I can go along with your suggestion I you believe this is best, however, if you are a bit uncertain, consider the possibility rolling it into the Reference section.  Hehe, if so we will have one less name to think of.

I think we are pretty much in agreement about the what should be in the document and it's order and structure.  I think we just need to sort out what names we want to give the three middle sections.   I have marked them with a '*' below just for clarity.

Title
Abstract
Contents
Description *
Structure *2
Reference *3
Revision History
License

If we can think of good names for Structure and Reference then we could keep Description as it is.  Of course the converse is also true so I guess the best thing is to brainstorm (i.e. make a list of possibilities and then choose after we have a big list).  Ok, I'll start it off and here is my list...

DESCRIPTION section's possible names
  • Description
  • Tutorial
  • Using Module
  • Using @Module Name@
  • Operation

    STRUCTURE section's possible names
  • Description
  • Structure
  • Module Structure
  • @Module Name@ Structure
  • Theory of Operation 
  • Operation
  • @Module Name@  Operation
  • @Module Name@  Internals

    REFERENCE section's possible names
  • Reference
  • Module API
  • Scripting
  • @Module Name@ API
  • @Module Name@ Reference
  • @Module Name@ Scripting
  • Scripting Reference
  • Scripting API

    It would be good to get opinions and ideas of others about the section names.  Let me know what everyone thinks and don't hesitate to  make suggestions.

    Programming Conventions
    Quote
    So the question is, should it just be an underscore character or maybe a longer prefix like "MUDULE_" or something simiar?
    Either one works for me, pick one.   

    Hehe, you mispelled MUDULE, which sounds/looks a lot like muddle, which is what we are trying to avoid.   ;D

    Quote
    A bit clumsy, I agree, but that's the only way out so far ...
    So should we recommend that or recommend doing the version check at runtime?  Perhaps at runtime is best because we could also do the warning thing then as well.  I guess the warning could be surpressed when DEBUG mode is disabled.

    Quote
    Well, that's another issue. The question is, should we made all global functions static?
    Ok, I understand.  That's actually a good idea because from the outside looking in everything looks consistent.  Why should some functions use an underscore and others use a dot?  It's too bad member variables can't be static.  That would make everything very consistent.  Is there any situation where this wouldn't work? 

    QuoteI think enum type name is only used by the autocompleter to list related enum values. Or do you mean something else? ...

    Unfortunetly, no. They all must be unique. I think it's a good idea to use prefix for module enums that in the header
    I meant to ask is there a difference in how enum names and values are defined (i.e. naming convention).  So you seem tot give the answer in your reply to my next question as follows:
  • Enum Names - IniFile_EnumName
  • Enum Values - IniFile_eEnumValue

    QuoteI agree on them. Well, maybe there could be exceptions for the internal implementation of the module. One may also want to use variable names like "loopCounter" or bFlag (with b have a meaning of "bool") etc.
    You mean have an optional lowercase prefix for "static variables" and "application functions"?  Yeah, I used that for the original Blue Gui to uniquely identify it from other code.  I guess I dropped it in favor of usingthe full module name for that purpose.  But I can see the usefulness of allowing such a prefix internally, especially for larger modules and for authors coming from a MS/VB world where variable names are commonly prepended with lowercase versions of the associated data type.   So, I agree we should include this option in the convention.

    QuoteYeah, sure there is no need to clutter up the source code with prefixes since they are not required there.
    Ok, agree.  We should remember to make a clear statment about this, otherwise well meaning authors may fall into this habit out of FUD.

    QuoteThink, yeah, I'll begin with module dependency stuff and then after it will be cleared up we can continue on other conventions. Module naming seems like the only difficult issue so far. Smiley Adding/editing document in turns seems to be a good idea. I also hope others will suppose ideas as well.
    That's great.  Thanks for helping, it's a real pleasure working with you.  I appreciate your comments and input to this process.  I always worry about missing or misstating something that is obvious. 

    QuoteSorry I've missed something because I'd written pretty much yesterday but was unlucky (or silly...) to accidently close the window thus wipping everthing out I had on the topic.
    Hehe, I'm sorry but you made me laugh out loud because I too have done this too many times and I am too emarassed to say so. :-[  It's scarry how like minded we are :=.

    Btw, do you remember that system plugin you did for me a while back?  What would you think of adding 7-zip or somthing similar to it?   I am thinking of making an app that, in addition to generating the document,  will collect the module.scm, document(s), and other releated files into a zip file named something like ModuleNameV100.zip.   

    I'm cleaning up the parser functions right now.   When I am done with that I will post a version for you to see what I am doing.   Then I will start work on document rendering.   I have an idea to use INI config files to specify the document  structure, so that the system will be flexible.  If things don't get too complicated I'll  implement it this way.   

    I look forward to hearing from you soon, providing you remember to hit the post button this time  :)

Scorpiorus

#13
Documentation

Quote from: RickJSo that's the reason for having Title and Abstract in stead of just one section that includes both informations.
Yeah, seems reasonable enough.

QuoteHehe, if so we will have one less name to think of.
That one should certainly be considered, since naming appears to be the most difficult issue so far, heh. Seriously, I was thinking further and maybe indeed leave it as it was planned before. Yes, I mostly considered separating the sections for large complex modules but now I'm getting inclined that it would become rather involved that way and make updating more difficult. Well, maybe if one will write such module they also have a chance to regard the possibility of including additional sections.


Thus one name to think, for the moment:

Title
Abstract
Contents
Description
Reference *
Revision History
License

And maybe really name it after module's name? "IniFile Reference", for instance.


Programming Conventions

Quote from: RickJ
Quote from: ScorpiorusSo the question is, should it just be an underscore character or maybe a longer prefix like "MUDULE_" or something simiar?
Either one works for me, pick one.
I'd take MODULE_ for the present but...
QuoteHehe, you mispelled MUDULE, which sounds/looks a lot like muddle, which is what we are trying to avoid.
That's rather worry -- bad omen!Ã,  :=
Or what about uppercasing it? IniFile -> INIFILE. Then again, it can bring confusion considering module's macros in the header have the IniFile_ prefix instead.

QuoteSo should we recommend that or recommend doing the version check at runtime?Ã,  Perhaps at runtime is best because we could also do the warning thing then as well.Ã,  I guess the warning could be surpressed when DEBUG mode is disabled.
On the other hand, it may be necessary to know a version number at compile time, because if, for example, our module requires version 2.0 of another module but there is only 1.0 available in the list, one will most likely get an "undefined token" error during the compilation on encountering a (function) name that was only introduced in version 2.0.

This, by the way, prompts me another idea on the module naming convention. What about only having IniFile_VERSION_100 etc. as a module name?

IniFile_VERSION_100
IniFile_VERSION_101
IniFile_VERSION_200
etc.

and
IniFile_VERSION could hold a version number to use at run-time, if necessary.

Indeed, what we really need is to check for the module version rather than its name. And if the version macros weren't defined then that means the module is not available:

#ifndef IniFile_VERSION
#error Can't find the required IniFile module!
#endif

#ifndef IniFile_VERSION_200
#error The IniFile module found but it doesn't meet the required version 2.0 or above!
#endif

Seems to be the best approach to me so far.

QuoteOk, I understand.Ã,  That's actually a good idea because from the outside looking in everything looks consistent.Ã,  Why should some functions use an underscore and others use a dot?Ã,  It's too bad member variables can't be static.Ã,  That would make everything very consistent.Ã,  Is there any situation where this wouldn't work?
I believe there should be no problems with that as static and global functions are basically the same. It's a pity we can't have static member variables, yeah.

QuoteThat's great.Ã,  Thanks for helping, it's a real pleasure working with you.Ã,  I appreciate your comments and input to this process.Ã,  I always worry about missing or misstating something that is obvious.
I too surely do! Hopefully, we'll come up with something that would be useful and easy for anyone to follow while they are writing their modules. :)

QuoteBtw, do you remember that system plugin you did for me a while back?Ã,  What would you think of adding 7-zip or somthing similar to it?Ã,  Ã, I am thinking of making an app that, in addition to generating the document,Ã,  will collect the module.scm, document(s), and other releated files into a zip file named something like ModuleNameV100.zip.
Sounds like a good idea to me. Sure, I'll see what I can do.

QuoteHehe, I'm sorry but you made me laugh out loud because I too have done this too many times and I am too emarassed to say so.Ã,  Ã, It's scarry how like minded we are.
QuoteI look forward to hearing from you soon, providing you remember to hit the post button this time
Hehe... I'm now writing this outside the browser and have already saved it for a dozen of times, just in case.Ã,  :=

RickJ

Documentation
QuoteI'm getting inclined that it would become rather involved that way and make updating more difficult. Well, maybe if one will write such module they also have a chance to regard the possibility of including additional sections.
That narrows it down quite a bit I'd say. 

Title
Abstract
Contents
Description
Reference*
Revision History
License

* Any of the following variations of "Reference" are acceptable and probably the best one is your suggestion of "IniFile Reference", where IniFile is the module name of course.

IniFile Reference
Script Reference
Refernece
Module Reference

On another note, Nethros has argeed to help us in this project.  He is good with HTML/CSS etc, so I thought he could help us with the document appearance and other web/html issues.   Since he is comming into the project with a fresh mind he may also be able to clear some of our mental blocks, perhaps help us think of names to call things, and generally give us some feedback on what we have done so far.   Somtimes basic questions from the uninitiated are very revealing and helpful.   So I am  looking forward to his participation.   Scrop, do you know of any HTML docs similar to what we are proposing that we can use as a starting point or example of the kinds of things that will be required?   

Programming Conventions
Quote
Or what about uppercasing it? IniFile -> INIFILE. Then again, it can bring confusion considering module's macros in the header have the IniFile_ prefix instead.
No,  no, no.  I was making a joke with the language.  Sorry if the humor didn't translate well.  I didn't mean to imply anything about macro naming or anything.  I just thought it ironic and funny that the mis-spelling made me think of the word "muddle" in the context of the discussion.  I just thought to share my amusement with you. 

QuoteThis, by the way, prompts me another idea on the module naming convention. What about only having IniFile_VERSION_100 etc. as a module name?
Yeah, your explanation of the issue is quite convincing.  I can envision a situation where a set of dependent modules evolve over time, making this scheme priceless. 

What would you think of just using a shorter version of the name like IniFile_V100. And is there a need to have one that tells what the latest version is? For example "#define IniFile_V000 IniFile_V201", where IniFile_V000  asways has the latest version.

And just to be sure I understand.... All modules would contain definitons of current and all previous release versions of the module.  Dependent modules check for the lowest acceptable versions of required modules.  Is this correct?

Should the file names carry the version number as well?  I was planning on this for the zip file but perhaps the other files should be named this way as well (i.e. IniFile_V100.scm).   Using the same name for the file and the macro is appealing to me for some reason. 

QuoteI believe there should be no problems with that as static and global functions are basically the same. It's a pity we can't have static member variables, yeah.
Hmmm, I thought of this work around
// Module Header
struct IniFile_Globals {
   // Global Variables
   int Foo;
   char Bar;

   // Global Functions
   import function FooBar(int foo, char bar);
}
import IniFile_Globals IniFile;

// Module Script 
IniFile_Globals IniFile;
export  IniFile_Globals IniFile;

function IniFile::FooBar(int foo, char bar) {
   this.Foo = foo;
   this.Bar = bar;
}

I am not sure if this actually works or if it's something we should suggest as it's a bit convoluted.   What do you think?   

QuoteI too surely do! Hopefully, we'll come up with something that would be useful and easy for anyone to follow while they are writing their modules.
Well, at least they will have a starting point and some guidelines to go by.

QuoteSounds like a good idea to me. Sure, I'll see what I can do.
Great, let me know what you come up with.  I looking forward to the discussions that are soon to follow.

Ok, I better get off the forum so I can get some work done instead of talking about it ;).  See you tomorrow...

SSH

Have you guys played around with the new single GUI import/export. Are the rules you are creating now applicable to these, too. I'm not sure yet how much script gets included with the .gue files... CJ, can you enlighten as to what exactly goes in there?

12

RickJ

#16
No we haven't thought about that but I guess we should consider that before we are done.  Do you have an ideas about what you would like to see?

SSH

Well, for exmaple, I'll have a module that uses a GUE as well, so the module dependecies will reflect that, and the GUE shoudl also have some comment in to mention the module, but since the GUE wont really have a lot of script (I'm guessing that it includes only GUI on_click and handler functions)  those will have to go INSIDE one/all of the functions.

Naming conventions: well, to avoid clashes, sicne the GUE fdunctions will go in a global script they'll need prefixes. And the defualt _Click suffix is probvabl;y a good convention to keep, too.  So far I've been prefixing all my gui object names with "go".

Other than that, I haven't really thoguht much
12

RickJ

Quote
Well, for exmaple, I'll have a module that uses a GUE as well, so the module dependecies will reflect that, and the GUE shoudl also have some comment in to mention the module, but since the GUE wont really have a lot of script (I'm guessing that it includes only GUI on_click and handler functions)  those will have to go INSIDE one/all of the functions.
Scrop has worked out a scheme where you can check for the presense of a module and flag a compiler error if it's not found.   So I guess you would check for a macro definition in one of the handler functions.  Probably it wouldn't need to be done in all of them since you would only need to generate one error.   

I had a look at the GUI editor and I managed to create the following handler function for a click on the GUI.  Is this more or less an equivalent of "interface_click(...) but for only a single GUI?  If so it would be my inclination to put the module dependency stuff in there, since it's the closest thing to a main function for the GUI.  I guess a good question is should this be the preferred method for GUIs of the type you desciribe?   I don't know the answer really because I haven't had time to play with this yet. 
function gSave_Click(GUI *theGui, MouseButton button) {
  
}

Quote
Naming conventions: well, to avoid clashes, sicne the GUE fdunctions will go in a global script they'll need prefixes. And the defualt _Click suffix is probvabl;y a good convention to keep, too.  So far I've been prefixing all my gui object names with "go".
Yeah, that's kind of why I was wondering if having a single handler for each individual GUI (as a convention) would be a good approach.  There would fewer names to worry about.   What do you mean by "GUI Object",  Buttons, Lables, etc or individual GUIs or something else?  Did CJ make it so that you could get to the controls via a path such as gSave.Ok or do we need to do something like gSaveOk for example,  to access the OK button on the SAVE gui? 


SSH

Quote from: RickJ on Thu 17/02/2005 09:52:53
Quote
Well, for exmaple, I'll have a module that uses a GUE as well, so the module dependecies will reflect that, and the GUE shoudl also have some comment in to mention the module, but since the GUE wont really have a lot of script (I'm guessing that it includes only GUI on_click and handler functions)  those will have to go INSIDE one/all of the functions.
Scrop has worked out a scheme where you can check for the presense of a module and flag a compiler error if it's not found.   So I guess you would check for a macro definition in one of the handler functions.  Probably it wouldn't need to be done in all of them since you would only need to generate one error.   

I had a look at the GUI editor and I managed to create the following handler function for a click on the GUI.  Is this more or less an equivalent of "interface_click(...) but for only a single GUI?  If so it would be my inclination to put the module dependency stuff in there, since it's the closest thing to a main function for the GUI.  I guess a good question is should this be the preferred method for GUIs of the type you desciribe?   I don't know the answer really because I haven't had time to play with this yet. 
function gSave_Click(GUI *theGui, MouseButton button) {
  
}


No, the function from the GUI is only for clicks on the GUI where there is no button. Buttons have their own, separate functions (although you can make them all point to the same function)

Quote
Quote
Naming conventions: well, to avoid clashes, sicne the GUE fdunctions will go in a global script they'll need prefixes. And the defualt _Click suffix is probvabl;y a good convention to keep, too.  So far I've been prefixing all my gui object names with "go".
Yeah, that's kind of why I was wondering if having a single handler for each individual GUI (as a convention) would be a good approach.  There would fewer names to worry about.   What do you mean by "GUI Object",  Buttons, Lables, etc or individual GUIs or something else?  Did CJ make it so that you could get to the controls via a path such as gSave.Ok or do we need to do something like gSaveOk for example,  to access the OK button on the SAVE gui? 

You can give each control its own name and access it directly, or you can use the gMYGUI.control[index]. prefix and then apply the AsButton, AsLabel, etc. to cast them to buttons, labels, etc as appropriate.


12

SMF spam blocked by CleanTalk