Script Module Guidelines discussion

[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]

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]

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?

[Scorpiorus]

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]

Publishing, Licensing

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...

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 ...

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?

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. 
  
  

  
  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
  

  
  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? 
  
  

  
  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
  

  
  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???
  
  

  
  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]

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();
};

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]

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?

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.

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]

Documentation

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. ...

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
  

  
  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
  

  
  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.   
  
  

  
  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]

Documentation

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?

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
  
  

  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.

  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

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. 
  
  

  
  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.
  
  

  
  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
  
  

  
  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 ..
  
  

  
  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" . 
  
  

  
  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
  
  

  
  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
  

  
  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

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:

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
  
  

  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" .

  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.
  
  

  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.

  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.
  
  

  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).

  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?
  
  

  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?

  A bit clumsy, I agree, but that's the only way out so far.
  
  

  What about global variables?
  IniFile_GlobalVariable

  Ah yeah thanks good point, forgot about them.
  
  

  What 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.
  
  

  Is 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?
  
  
  

  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?

  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
  };
  
  

  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.

  Entirely agree.
  
  

  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.

  Second that! That's why I mentioned about the "object" name, for instance. Just to make sure it was stated at least once!
  
  

  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:

  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.
  
  

  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.

  Yeah, sure there is no need to clutter up the source code with prefixes since they are not required there.
  
  

  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?

  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

... 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.

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.   

... 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.

./.. 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
  

  
  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.   
  
  

  
  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.
  
  

  
  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? 
  
  

  I 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
  
  

  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.
  

  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.
  
  

  Yeah, 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.
  
  

  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. 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. 
  
  

  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.
  

  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]

Documentation

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

Yeah, seems reasonable enough.

Hehe, 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

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.

I'd take MODULE_ for the present but...

Hehe, 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.

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.

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.

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?

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.

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.

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.

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.

Sounds like a good idea to me. Sure, I'll see what I can do.

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.

I 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

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.

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

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. 

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?

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. 

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.

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?   

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.

Well, at least they will have a starting point and some guidelines to go by.

Sounds 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?

[RickJ]

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

[RickJ]

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) {
  
}

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]

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)

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.

[Scorpiorus]

Documentation

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.

Ok, it's almost resolved here. Whatever it will be named but it's only a single section name to think of, that's relieving.

On another note, Nethros has argeed to help us in this project.

Cool! It's nice to see new participants being interested.

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?

Not quite, at the moment, but I'll see if I can find something relevant.


Programming Conventions

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.

Hehe, no I certainly got the joke but, the funny thing is, it also incited me to re-think the issue and finally to come up the IniFile_VERSION-as-a-name thingy that I should have thought of in the first place actually.

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?

Yeah, I thought about having a shorter name but here is what urged me to suggest the original convention:

Suppose, we're making a new module, thus it must have a version, so we define a macro in our module's header (taking IniFile as module name):

#define IniFile_VERSION 100

The neatest thing, this macro's name entirely meets the macro naming convention for modules we were discussing (i.e. IniFile_ is a mix-cased prefix). So, what we can state in the conventions document is that each module *must* have a version macro defined in the very same way. This macro is to be checked by other dependent modules and thereby it can be determined whether the required module exists and its exposed functionality can be used. This macro is also stores the module's current version which can be checked at run-time if necessary (IniFile_V000's analog).

Unfortunetly, the value of version macro can't be used at compile time, therefore there is a necessary to introduced other macros as well:

#define IniFile_VERSIONÃ,  200

#define IniFile_VERSION_200
#define IniFile_VERSION_150
#define IniFile_VERSION_102
#define IniFile_VERSION_101
#define IniFile_VERSION_100

Yes, the module must have all of them. Module developer is just supposed to add a new version name (as well as to change IniFile_VERSION value) each time a new version of a module is released. I named them mainly after the original macro (to be consistent) but having shorter names instead is also a possibility.

What I really hope for, is that these macros are temporary. If in a future version of AGS it were possible to check conditions while pre-processing then these additional macros would become obsolete but the scheme would still work:

Thus older dependent modules would check required modules as:

// if module version is not even defined (word for word btw )
#ifndef IniFile_VERSION
#error Can't find the required IniFile module!
#endif

// if the module is here but the version is too old:
#ifndef IniFile_VERSION_102
#error IniFile version 1.02 or higher required!
#ifndef


The newer ones would do:

// if module version is not even defined:
#ifndef IniFile_VERSION
#error Can't find the required IniFile module!
#endif

// if the module is here but the version is too old:
#if IniFile_VERSION < 102
#error IniFile version 1.02 or higher required!
#ifndef

No need for IniFile_VERSION_102, etc. this way.

By the way, it should be noted that in any case a new version of a module should also support functionalities of previous versions as well, i.e. the exposed but obsolete functionality should not be removed in order to ensure all dependent modules would work correctly. Such functionality can however be hidden from the autocomplete feature so that the chance it will be used in future would be minimal.
This would make modules backward compatible.

And to be honest the more I think about it the more it seems to me that such dependence checking is to be better supported natively by the editor because it could then also sort the modules list as necessary. I can already foresee difficulties with arranging them manually in case of a large number of dependent modules.

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).

It's ok with me, I too like naming them like that. Maybe it should be left up to the author, not certain here.
By the way, AFAIK it is not possible to have two versions of the same module in the module list. When a new module is created it's also assigned a key ID that makes it be unique. If the module with the same key as a module to import is already in the list the editor won't allow importing a new one. It is not therefore, by the by, a good idea to release a brand new module by replacing the source code of the existing one and then exporting it. Those two modules would collide if imported into the same project. So a new module, the "New..." button! Moreover, it means we can't have some kind of a module template by just exporting a dummy one but with examples of version or/and dependencies macros/checkings inside.

Using the same name for the file and the macro is appealing to me for some reason

Oh, hehe that's probably another good reason for using shorter version names.

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.

Hmmm, I thought of this work around... 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?

Yeah why not, nice trick! As long as there is no need to also create other instances of "IniFile" (i.e. there is no IniFile struct).
This can actually be not revealed to the module user or, on the countrary, clearly said that there is a single exposed IniFile instance to access module's functionality. So, I think, it's up to the developer as the module name can really be used as one likes, I think.

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.

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.

Yeah, if a certain GUI is connected with the module (calls into it) the module presence can be checked within one of the GUI functions, I believe (it doesn't matter which one as long as its code is transported along with the exported GUI) or maybe even outside the function but inside #section* block (didn't test that though):

#sectionstart gSave_Click
// <--maybe placing it here is also ok (assuming it will be exported that way)
function gSave_Click(GUI *theGui, MouseButton button) {

#ifndef ImportantGUIModule_VERSION
#error Can't find the necessary ImportantGUIModule module!
#endif

}
#sectionend gSave_Click


On the other hand, if a module needs to know whether a GUI exists it can look for its original name:

module script:

#ifndef STATUSLINE
#error Can't find the STATUSLINE GUI!
#endif

Which also as well brings us back to the naming conventions, GUIs now...

[Pumaman]

And to be honest the more I think about it the more it seems to me that such dependence checking is to be better supported natively by the editor because it could then also sort the modules list as necessary. I can already foresee difficulties with arranging them manually in case of a large number of dependent modules.

If it becomes a problem, then some sort of native dependency support would be a good idea. However, I don't forsee there being lots of modules with dependencies since as I see it modules will generally be contained as a unit and not rely on external things.

[RickJ]

Documentation

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.

Ok, it's almost resolved here. Whatever it will be named but it's only a single section name to think of, that's relieving.

Agree.  have you ever heard the phrase "It's close enough for goverment work!" 

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?

Not quite, at the moment, but I'll see if I can find something relevant.

I surfed around last night for examples of API type documents and how they show function proto-types, code examples, etc.   Since we pretty much settled on the organization, we only need some examples of how different kinds of things can be presented just to get a discussion started.  Maybe SSH has knows of some examples. 

Programming Conventions

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.

Hehe, no I certainly got the joke but, the funny thing is, it also incited me to re-think the issue and finally to come up the IniFile_VERSION-as-a-name thingy that I should have thought of in the first place actually.

Hehe, funny how things work out sometimes.  After reading your other comments on the subject I like the IniFile_VERSION scheme very much.   The longer macro names (i.e. IniFile_VERSION_100, etc) also make more sense to me now as well.  So I am persuaded that we should go with this.   

What I really hope for, is that these macros are temporary. If in a future version of AGS it were possible to check conditions while pre-processing then these additional macros would become obsolete but the scheme would still work:

// if the module is here but the version is too old:
#if IniFile_VERSION < 102
#error IniFile version 1.02 or higher required!
#ifndef

Yeah, that would be a really cool way of handling it.   

By the way, it should be noted that in any case a new version of a module should also support functionalities of previous versions as well, i.e. the exposed but obsolete functionality should not be removed in order to ensure all dependent modules would work correctly. Such functionality can however be hidden from the autocomplete feature so that the chance it will be used in future would be minimal.
This would make modules backward compatible.

Very true.  We need to remember to make this clear in any guidelines we make.

And to be honest the more I think about it the more it seems to me that such dependence checking is to be better supported natively by the editor because it could then also sort the modules list as necessary. I can already foresee difficulties with arranging them manually in case of a large number of dependent modules.

I agree, but I don't think that will happen this go around though.  I wish we were able to read and write the fields in the Module Manager as well.   Then I could make sure the version number there matched what's in the header etc. 

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).

It's ok with me, I too like naming them like that. Maybe it should be left up to the author, not certain here.

I'm thinking to auto-generate the zip file name from the module name and version via some kind of "Release Module" command, which would make the zip file in a specified folder. 

By the way, AFAIK it is not possible to have two versions of the same module in the module list. When a new module is created it's also assigned a key ID that makes it be unique. If the module with the same key as a module to import is already in the list the editor won't allow importing a new one. It is not therefore, by the by, a good idea to release a brand new module by replacing the source code of the existing one and then exporting it. Those two modules would collide if imported into the same project. So a new module, the "New..." button! Moreover, it means we can't have some kind of a module template by just exporting a dummy one but with examples of version or/and dependencies macros/checkings inside.

Wow!  I didn't know about the unique ID thingy, that's very interesting.   

I asked CJ about the possibility of having a default module and room templates.  He said that there is already this possibility with rooms. You put something like _blank.crm in the game folder and "New Room" uses this file as a template.  He didn't say if or when he would do the same for modules.  At the time I assumed that he would do so eventually, however, in light of what we are doing I think it would be a good idea to specifically request it. What do you think?

Using the same name for the file and the macro is appealing to me for some reason

Oh, hehe that's probably another good reason for using shorter version names.

Except that you have already persuaded me that the longer macro names are better.  :  Appealing as it is, I haven't made as good a case for it as you have for the longer names.   However file names can still include the version number like this IniFile_V200.zip.

Yeah why not, nice trick! As long as there is no need to also create other instances of "IniFile" (i.e. there is no IniFile struct).
This can actually be not revealed to the module user or, on the countrary, clearly said that there is a single exposed IniFile instance to access module's functionality. So, I think, it's up to the developer as the module name can really be used as one likes, I think.

Oh yeah, now I see the flaw.  There is the possibility of name collsions, so I think this is not such a good idea, just using norma global variables are  probably a better idea.   In cases where there is a one on one correspondance between the module and the primary struct (i.e. OO object), I would prefer having the possibity of giving the same name as the struct as I have done in the actual IniFile module.  IMHO, this is more intuitive than giving some other name to the struct.  For this reason I would reject my own idea.  Thanks for enlightening me.

... Which also as well brings us back to the naming conventions, GUIs now...

[Scorpiorus]

If it becomes a problem, then some sort of native dependency support would be a good idea. However, I don't forsee there being lots of modules with dependencies since as I see it modules will generally be contained as a unit and not rely on external things.

Yeah, I'm not certain how things will go but I agree it obviously isn't a high priority feature for now. Sorry if it sounded like an instant request, I didn't want to even mention it at first, but eventually couldn't resist.

Agree.Ã,  have you ever heard the phrase "It's close enough for goverment work!"

... Which also as well brings us back to the naming conventions, GUIs now...

Yeah you mean like it's as usual "close enough"?


Programming Conventions

After reading your other comments on the subject I like the IniFile_VERSION scheme very much.Ã,  Ã, The longer macro names (i.e. IniFile_VERSION_100, etc) also make more sense to me now as well.Ã,  So I am persuaded that we should go with this.

I'm glad you liked it! Still, the case hasn't been closed so if anyone have any toughts on how this approach can be improved/enhanced, please let us know.

I agree, but I don't think that will happen this go around though.Ã,  I wish we were able to read and write the fields in the Module Manager as well.Ã,  Ã, Then I could make sure the version number there matched what's in the header etc.

Hehe, what we should only worry about is to bring anyone who follows the guidelines to remember to update the module's version info as well as the version macros themselves, that's for sure. I appreciate one may wish it to be semi-automatic at least but currently there are three steps to pass -- add a new macro, change other macro value and finally don't forget to reflect the version number in the appropriate property to be displayed next to the module name.

He didn't say if or when he would do the same for modules.Ã,  At the time I assumed that he would do so eventually, however, in light of what we are doing I think it would be a good idea to specifically request it. What do you think?

Having some sort of a module template would be nice, I agree yeah. Implementing it, again, depends on how badly it is needed for the moment, I guess.

Except that you have already persuaded me that the longer macro names are better.

Hehe, but I didn't know for sure if I would do.Ã, 

However file names can still include the version number like this IniFile_V200.zip.

Yeah, I'm all for it too.

Oh yeah, now I see the flaw.Ã,  There is the possibility of name collsions, so I think this is not such a good idea, just using norma global variables areÃ,  probably a better idea.

I think sometimes it may be useful. Yep, it's mostly when there is no a struct supposed to be, so it can then be used for grouping both the global functions and variables as you described.

[RickJ]

If it becomes a problem, then some sort of native dependency support would be a good idea. However, I don't forsee there being lots of modules with dependencies since as I see it modules will generally be contained as a unit and not rely on external things.

Yeah, I'm not certain how things will go but I agree it obviously isn't a high priority feature for now. Sorry if it sounded like an instant request, I didn't want to even mention it at first, but eventually couldn't resist.

We're thrilled to have a module mechanism and trying to be thorough in our review.   Likely we will end up at the end of this process with a wish list containing items like this.   You rightly point out, that it will become appparent, in due time, which, if any of these are meritorious.   

Agree.  have you ever heard the phrase "It's close enough for goverment work!"

... Which also as well brings us back to the naming conventions, GUIs now...

Yeah you mean like it's as usual "close enough"?

Yeah, that's pretty close to the meaning.     Goverments always spend too much money for everything and usually don't care much about the quality. 

Programming Conventions

After reading your other comments on the subject I like the IniFile_VERSION scheme very much.   The longer macro names (i.e. IniFile_VERSION_100, etc) also make more sense to me now as well.  So I am persuaded that we should go with this.

I'm glad you liked it! Still, the case hasn't been closed so if anyone have any toughts on how this approach can be improved/enhanced, please let us know.

I shall also  listen...

I agree, but I don't think that will happen this go around though.  I wish we were able to read and write the fields in the Module Manager as well.   Then I could make sure the version number there matched what's in the header etc.

Hehe, what we should only worry about is to bring anyone who follows the guidelines to remember to update the module's version info as well as the version macros themselves, that's for sure. I appreciate one may wish it to be semi-automatic at least but currently there are three steps to pass -- add a new macro, change other macro value and finally don't forget to reflect the version number in the appropriate property to be displayed next to the module name.

Actually, I think I can get the Module Manager's version number out of the SCM file, while extracting the documentation.  I could then,  perhaps verify that all three steps have been done correctly?

He didn't say if or when he would do the same for modules.  At the time I assumed that he would do so eventually, however, in light of what we are doing I think it would be a good idea to specifically request it. What do you think?

Having some sort of a module template would be nice, I agree yeah. Implementing it, again, depends on how badly it is needed for the moment, I guess.

I think put this on our wish list and at the end we can maybe llist them in orfer of importance as is our opinion and then let nature take it's course.

Except that you have already persuaded me that the longer macro names are better.

Hehe, but I didn't know for sure if I would do. 

Hehe... this could get circular

However file names can still include the version number like this IniFile_V200.zip.

Yeah, I'm all for it too.

Cool  8)

Oh yeah, now I see the flaw.  There is the possibility of name collsions, so I think this is not such a good idea, just using normal global variables are  probably a better idea.

I think sometimes it may be useful. Yep, it's mostly when there is no a struct supposed to be, so it can then be used for grouping both the global functions and variables as you described.

I think your approach, using static functions and global variables is a better solution.  For example in the actual IniFile module I use IniFile as the main struct name.  I could still add static functions as you suggest without any problems.  With my suggestion I would run into a naming problem, in that I coldn't use IniFile for both the struct name and the instance of the struct.   So, Yeah some could do what I suggest if they had a really good reason, but  otherwise they would be better using static functions.   Maybe we put a request for static variables in the wish list also.
======

Ok!  It looks like we have settled many issues.  I'm sure others will come up soon enough.   Back to work now...

[Scorpiorus]

Actually, I think I can get the Module Manager's version number out of the SCM file, while extracting the documentation.  I could then,  perhaps verify that all three steps have been done correctly?

Ah, yeah that would be great!

I think put this on our wish list and at the end we can maybe llist them in orfer of importance as is our opinion and then let nature take it's course.

Good idea, it will then be evident what is really needed.

So, Yeah some could do what I suggest if they had a really good reason, but  otherwise they would be better using static functions.

Yep, in case they are writing some kind of a library-module (i.e. just a set of related functions and possibly global vars) and thus can use an instance to group all of them together.

Maybe we put a request for static variables in the wish list also.

Ok with me

Back to work now...

By the way, what minimum length should a module name have? I appreciate the shorter the name the greater the possiblity of name collisions. Longer names, on the other hand, could clutter the source code, especially if a module has several exposed structs.

struct ModuleName_StructName {
...
};

But then again, such names would mainly be used to declare variables (so the length doesn't really matter here) and we also have the great autocomplete feature.

So the question is, how short a module name can be?

[RickJ]

By the way, what minimum length should a module name have? I appreciate the shorter the name the greater the possiblity of name collisions. Longer names, on the other hand, could clutter the source code, especially if a module has several exposed structs.

That's a tough question  :.  I'm certain that there at least a half dozen opinions on the subject  .  However, I guess I would say at least "2 or 3" should be required and probably something like "7 or more" should be the recommendation.   I can see using the shorter names for library type things. 

============
For anyone interested here is a link to a pre-alpha version of the document generator.  Currently it reads the first 100 lines from the IniFile.s file, analyses the line's content and displayss the results in the left hand column of the screen.   The actual line that was read is displayed at the top of the screen.  The document is displayed under the current line as it is being read.   

ScriptDoc_V001A01.zip

The design goal of the parser was to make it very modular so consequently some of the processing is duplicative. I believe this will not be a problem because the file size of the documents are relatively small. 

No I can start working on doing the document output.  This should be a bit more fun and a little less tedious than the parser.   I am thinking of using a config file to define how and what to extract from the input file.  This would allow us to use it for other purposes.  I'll see how it goes and if it's practical. 

Oh well, feel free to let me know what you think.   Cheers!!!

[Scorpiorus]

Good work with the parser, Rick!

I am thinking of using a config file to define how and what to extract from the input file.

Would be handy, yeah. Especially considering that we are not yet decided what exactly would be extracted etc. Having some versatility would never hurt.

However, I guess I would say at least "2 or 3" should be required and probably something like "7 or more" should be the recommendation.

Yeah agree, maybe 3 at least, because that's the number of characters one types-in in order for the autocomplete list to pop up.

[SSH]

Sorry to drag up an old-ish topic, but did you guys reach a conclusion here, and any chance of writing it up in a printable format?

[RickJ]

SSH, thanks for bumping the thread.  Yeah, I think we reached a concensus of opinions.  Scrop said he would write up something about the "#define Version" stuff.  I plan on writing up something on naming conventions etc.   I have had to take a temporary break from this to  get DemoQuest in shape for the new AGS releasel.   Do you have an immediate need or is this more of a general inquiry?  If there is anything I can help you with please just let me know. 

Cheers 

[SSH]

Well, I think it would be a good idea to have it written up by the time that AGS 2.7 is released, which may be April 1st.... with the new shareware licence

I dunno if CJ would consider distirbuting the guidelines with the release?

Also, once 2.7 is out, I want ot do a proper release of my savegame with screenshots module and GUE.

[RickJ]

SSH,

Here is a first draft of a document that drescribes what I believe was the concensus of the discussion in this thread.  If something needs to be changed or added please let me know.

• ModuleProgrammingGuidlines
  
• ModuleScriptTemplate
  
• ModuleHeaderTemplate

[strazer]

Nice work!

1.) Shouldn't #defines, static variables and utility functions in the module script also be prefixed with the module name as not to collide with anything the game author may have set up in the global script header?

Btw, I like "Internal functions" better than "Utility functions".

2.) If only a specific function depends on another module, we should suggest to use
  #ifndef YourModule_VERSION
    AbortGame("Can't find required module 'YourModule'!");
  #endif

And few spelling errors:

static
member functions are recognized but the auto-complete feature of the
Script Editor.

   // Note: String variables are ->NOT<- permitted inside a
   // struct.  Use a char array instead.

outside the bounds of any fucntion

give credit where credit is do.

"Derrived from IniFile by RickJ"

copiler errprs

apporpiate error message

[RickJ]

1.) Shouldn't #defines, static variables and utility functions in the module script also be prefixed with the module name as not to collide with anything the game author may have set up in the global script header?

I don't believe the Global Script Header is included into Module Script, only the Module Header. 

Btw, I like "Internal functions" better than "Utility functions".

I suppose there could be a whole discussion about both terms "Utility" and "Application" to possibly come up with better names.   I choose to apply "Utility" to the functions that do all the dirty work and "Application" to the functions that provide a clean interface to some high level functionality.   In my mind "Internal" seems to apply equally to both. 

Does anyone else have opinions about this?

2.) If only a specific function depends on another module, we should suggest to use
  #ifndef YourModule_VERSION
    AbortGame("Can't find required module 'YourModule'!");
  #endif

The #ifndef, #endif, #error,  ect.. are directives that are only executed at compile time.   AbortGame() is a function called at runtime.  The #error directive does more or less the samething as AbortGame() but at compile time instead of at runtime.   Having said that, a variation of your idea would make it possible to use only one macro definition to manage dependancies. 

You would check for the existence of the module in the Module Header as Scorp suggested.  If YourModule is not imported into AGS prior to MyModue being imported into AGS then an error is generate by the compiler.  So far this is what is currently suggested. 

Now to check the version of YourModule, this could be done at runtime, as you suggest Strazer, instead of doing it at compile time as Scrop suggests.  The advantage of doing it at runtime is that only one macro will be required;  there is always a possibility of someone deleting those additional version macros from some future version of the module and breaking other modules.   The disadvantage is, ofcourse, that the error won't be detected until runtime.   Here is an example of what I am talking about.

// YourModule Module Header
#define YourModule_VERSION 200 

// MyModule Module Header
#ifndef YourModule_VERSION
#error *** Error-MyModule, can't find required module 'YourModule'!
#endif

// MyModule Module Script
function start_game() {

   // Check module dependancies
   if (YourModule_VERSION<150) {
      AbortGame("*** Error-MyModule, version YourModule V1.50 or greater required");
   }
}

Any comments about this ?  SCROP, SSH, etc...

copiler errprs

Hehe!    I find that one funny.   ALso, why do we call them "compiler errors" when in fact it was the programmer who made the error and not the compiler?  Perhaps from now on they should be refered to a s"programmer errors"?   

In any case thanks for checking my spelling.  I'll get right on it and correct those "author errors".

==================

Also, I would like to add you guys to the credits of this document as it is just a summary of our discussion here.  So if you would like me to do so please PM me your  frist, last, and forum name so that I can add it to the document.   

Cheers

[strazer]

I don't believe the Global Script Header is included into Module Script, only the Module Header. 

Hey, you're right. Good to know. I assumed it is.

In my mind "Internal" seems to apply equally to both. 

You have a point. Still, I think the difference between "Internal functions" and "User functions" is more obvious.

The #error directive does more or less the samething as AbortGame() but at compile time instead of at runtime.

I know. What I mean is, if only one function of your module depends on another module, but this function is not even used by the game author, IMO the dependency shouldn't be enforced.
Instead, you could do:

Code: ags

static function MyModule::DoSomeStuff() {

  #ifndef MODULE_YOURMODULE
    AbortGame("This function depends on 'YourModule'!");
  #endif

  // (the stuff)

}

The game author will know that he has to import another module the moment he tries to use the function.

Edit:

#error *** Err-MyModule, can't find required module "YourModule"!

"Err-MyModule" isn't needed as the AGS error message displays the module name where the error was raised.

Edit 2:

At the time of this writing, it is not clear to the author what scope or other charactistics enums defined in the Module Script have

Good question.

[Scorpiorus]

Digging it up...

Sorry to drag up an old-ish topic, but did you guys reach a conclusion here, and any chance of writing it up in a printable format?

SSH, thanks for bumping the thread.  Yeah, I think we reached a concensus of opinions.  Scrop said he would write up something about the "#define Version" stuff.  I plan on writing up something on naming conventions etc

I did start making a doc about module dependencies but got wiped it all out as my hard drive crashed. It took pretty much time to set the system up again and finally be online. Fortunately, this thread contains all the info regarding dependencies stuff so I think it won't be a big problem to rewrite from scratch.

Shouldn't #defines, static variables and utility functions in the module script also be prefixed with the module name as not to collide with anything the game author may have set up in the global script header?

Yeah, as Rick has already said the global script header is not attached to the script of a module, thus everything that's declared within the module's script and is not exposed via its header is not seen from within any other scripts. Here is a post I made after investigating the mechanism: http://www.adventuregamestudio.co.uk/yabb/index.php?topic=19369.msg230174#msg230174

In my mind "Internal" seems to apply equally to both. 

You have a point. Still, I think the difference between "Internal functions" and "User functions" is more obvious.

I like "internal functions". It, indeed, may also be internal functions and user functions or possibly internal functions and interface functions. As a module user I'd probably want them to be refered as user functions, ex: "This module provides you with the following user functions..." or "the following user functions are available".

The #error directive does more or less the samething as AbortGame() but at compile time instead of at runtime.

I know. What I mean is, if only one function of your module depends on another module, but this function is not even used by the game author, IMO the dependency shouldn't be enforced.
Instead, you could do:

Code: ags

static function MyModule::DoSomeStuff() {

  #ifndef MODULE_YOURMODULE
    AbortGame("This function depends on 'YourModule'!");
  #endif

  // (the stuff)

}

The main problem with having any run-time modules dependency error messages is that it's not actually possible to make a game run (and thus see the message) until you get rid of every single line which calls into the module we depend on. That's why #error directive comes in handy, it reports at compile time instead.

The code in question will not compile if the MyModule::DoSomeStuff function has any calls (and it has, since it depends) into YourModule, we just get undefined token error.

We could of course omit this module check and just let the compiler to report about the undefined token but this will likely confuse a user since (s)he wouldn't have an info regarding what module (and what its version) (s)he is required to install.

As for where to put such dependency checks, a general rule would be - before the first client module's line which code invokes any function of a servicing module.

If it's a single function that depends on a module than, yep, just put a check within this function but before any implementation code:

Code: ags

static function MyModule::DoSomeStuff() {

  #ifndef YourModule_VERSION
      #error This function depends on 'YourModule'!
  #endif

  YourModule_SomeUserFunction(); // calling YourModule function

}

But I appreciate that sometimes there could be some tricky ways of handling dependency issues when we woud like to replace missing functionality with our own implementation if the required module isn't there, or call AbortGame function as a special case. Then we'd need to wrap all the code with #if-#endif:

Code: ags

static function MyModule::DoSomeStuff() {

  #ifndef MODULE_YOURMODULE
       AbortGame("This function depends on 'YourModule'!");
  #endif
  #ifdef MODULE_YOURMODULE
       YourModule_SomeUserFunction(); 
  #endif
}

As for dependent modules, we could put checks within their headers just in case these headers use some of declarations made in servicing modules.

EDIT:

At the time of this writing, it is not clear to the author what scope or other charactistics enums defined in the Module Script have

Good question.

If I get it right, all the enums defined in the module script are local to the module itself (just like any struct defined within it) so we shouldn't worry about it. Their names must of course differ from AGS internal enums as all scripts (module, global, room) are preceded by what I'd call the internal script header where all game structs and functions are defined (Character, Object, Enums, etc.).

[RickJ]

did start making a doc about module dependencies but got wiped it all out as my hard drive crashed. It took pretty much time to set the system up again and finally be online. Fortunately, this thread contains all the info regarding dependencies stuff so I think it won't be a big problem to rewrite from scratch.

Scorp,   While you were gone SSH asked me what conconlsions we had reached so I had a go at making the document which includes a section about the dependancies. So instead of starting from scratch perhaps you could review what I have already done and make any changes you think are appropriate.  Here are the three documents I gave to SSH.

• ModuleProgrammingGuidlines
  
• ModuleScriptTemplate
  
• ModuleHeaderTemplate

[Scorpiorus]

Thanks Rick, the links didn't work the time I was replying but thanks for bumping it up -- I've now read the latest version of the document.

Dependencies section looks good, states everything we were talking about. But what do you think of adding a convention to check if module with the same name already exists? That is:

#ifdef MyModule_VERSION
#error Error: module with the same name already on the list!
#endif

// Version Macro Definitions
#define MyModule_VERSION 200
#define MyModule_VERSION_200
#define MyModule_VERSION_150
#define MyModule_VERSION_102
#define MyModule_VERSION_101
#define MyModule_VERSION_100

It's just in case two or more module authors would make script modules with identical names, independently of each other.


Also, what if there would be a demo script module? It would basically be a simple working module (eg: math functions) that just shows all the conventions in work. The key point is to make it very simple but still demonstrating every single rule (notations, etc.).

[RickJ]

But what do you think of adding a convention to check if module with the same name already exists?

If a game contains MyModule you can't import another module named MyModule.  If this is what you mean then I think it is already prevented.

Also, what if there would be a demo script module? It would basically be a simple working module (eg: math functions) that just shows all the conventions in work. The key point is to make it very simple but still demonstrating every single rule (notations, etc.).

I like that idea very much.  That was my motivation in making the template files.  I think having an example to go along with them would be a very good idea.   

Perhaps this example should be in the form of  a AGS Game Template (*.agt)  that would contain two modules  ExampleModule containg the example you suggest and NewModule containing empty templates.  This way if someone wanted to make a new module they could use this template to create a new game.  The could rename NewModule to whatever they wanted and start coding.  They could look at ExampleModule whenever they wanted to see how to do things. 

We could also add functionality to the game proper to help in the test process.  There could be GUI's, test room, etc to aid in development.

=====
Btw, I was reviewing the thread and was wondering about the issues SSH brings up.   When he orignally posted I wasn't up to speed on the GUI stuff and overwhelmed with the DQ update.   Would you mind taking a look at his suggestions and let me know what you think.   One of the things he mentions is using the prefix "go" for all of his gui objects.   In DemoQuest I just used the gui name to prefix the objects it contains.  I didn't realize until now that this is one of the things SSH was asking about and had previoously made suggestions.     

In any case this is probably a good time to have a discussion about this.  If we reach a conclusion I can go back and modify DemoQUest to conform to whatever we decide before it is released.

[Scorpiorus]

If a game contains MyModule you can't import another module named MyModule.Ã,  If this is what you mean then I think it is already prevented.

Yeah, however there is a particular case when two modules can have identical Name_VERSION macros but different names (those appear in the module manager list) and keys.
At present, conventions document states that a module name from the manager list should be in Camel Notation and thus, if I get it right, also be identical to the prefix of the version macro. It is not required to do any extra checks if it's the case but on the other hand I'm not sure if we should restrict module's full name to Camel Notaion. Because the name edit box in the module manager actually allows any string as a module name and, for example, an extra space character could break the rule. And I believe it is meant to be a full name, not just abbreviation. It is becoming important when a prefix is an abbreviation or acronym of the module's name. For example, one would like to name a module "NewObjectFunctions" but have "NOF" as a profix; or have "Math" or "MFL" for "Math Functions Library".
Suppose in a future, AGS will have functionality of handling module dependencies. There will then be a need to introduce another type of module name, the one that we currently use to prefix exposed functions, types, defines and variables. Then the current module name in the manager would be a full name of a module while the new name would be a unique identifier of the module. Just like characters have names and script names. What do you think?

Perhaps this example should be in the form ofÃ,  a AGS Game Template (*.agt)Ã,  that would contain two modulesÃ,  ExampleModule containg the example you suggest and NewModule containing empty templates.

Yeah, agreed. With that ExampleModule one could browse it while reading the conventions document. Module templates, on the other hand, are to be used by someone to actually start off developing their own script modules.

We could also add functionality to the game proper to help in the test process.Ã,  There could be GUI's, test room, etc to aid in development.

Do you mean some stuff to debug the user code?

Btw, I was reviewing the thread and was wondering about the issues SSH brings up.Ã,  Ã, When he orignally posted I wasn't up to speed on the GUI stuff and overwhelmed with the DQ update.Ã,  Ã, Would you mind taking a look at his suggestions and let me know what you think.Ã,  Ã, One of the things he mentions is using the prefix "go" for all of his gui objects.Ã,  Ã, In DemoQuest I just used the gui name to prefix the objects it contains.Ã,  I didn't realize until now that this is one of the things SSH was asking about and had previoously made suggestions.

Yeah, I too browsed it again and indeed the doc doesn't mention anything concerning GUIs. I'm for using a GUI name to prefix its objects(controls) names since just like with module functions and variables GUI controls are contained within a GUI, eg: GUI5_Button3, GUI5_Button3_Click.
But whether GUIs should be prefixed - is still a question.
If it's a specific module GUI I'd use a module name to prefix it:
MyModule_MyGUI
MyModule_MyGUI_Button1
MyModule_MyGUI_Button1_Click

What do you think about the problem?

[strazer]

Perhaps this example should be in the form of  a AGS Game Template (*.agt)  that would contain two modules  ExampleModule containg the example you suggest and NewModule containing empty templates.  This way if someone wanted to make a new module they could use this template to create a new game.  The could rename NewModule to whatever they wanted and start coding.

I don't think this will work. AFAIK modules get assigned a unique ID internally when they are created and you can't have two modules with the same ID. That means end users won't be able to mix modules that have been created from this template.

I'm for using a GUI name to prefix its objects(controls) names since just like with module functions and variables GUI controls are contained within a GUI, eg: GUI5_Button3, GUI5_Button3_Click.
But whether GUIs should be prefixed - is still a question.
If it's a specific module GUI I'd use a module name to prefix it:
MyModule_MyGUI
MyModule_MyGUI_Button1
MyModule_MyGUI_Button1_Click

What do you think about the problem?

I agree, prefix everything that is linked to a module.

[Scorpiorus]

I don't think this will work. AFAIK modules get assigned a unique ID internally when they are created and you can't have two modules with the same ID.

Yep, that's the only problem with having a module template in a form of an already created script module. IIRC, we discussed a possibility of having some sort of module template feature built-in AGS; making a module template as two pure text files can serve as a workaround for now I believe.

I agree, prefix everything that is linked to a module.

Funny enough, after have posted that suggestion I just discovered that the underscore character can't be a part of a GUI name.

[strazer]

I agree, prefix everything that is linked to a module.

Funny enough, after have posted that suggestion I just discovered that the underscore character can't be a part of a GUI name.

Also, GUI names can only be 14 characters long...

Going back, I think adding the GUI name to the GUI control script name like
  MyModule_MyGUI_Button1
is not necessary. Isn't
  MyModule_btnDoSomething
better? Naming the control for what it does?

[SSH]

I don't think this will work. AFAIK modules get assigned a unique ID internally when they are created and you can't have two modules with the same ID.

Yep, that's the only problem with having a module template in a form of an already created script module. IIRC, we discussed a possibility of having some sort of module template feature built-in AGS; making a module template as two pure text files can serve as a workaround for now I believe.

so, someone make a tracker entry then...

[strazer]

Honestly, I don't think this feature is needed at all.
Any user that is sophisticated enough to want to publish his own script modules doesn't need a built-in template system. The guidelines and some template text files are enough IMO.

[Scorpiorus]

Also, GUI names can only be 14 characters long...

Indeed... Moreover, the actual GUI script O-Name would be gMyModule_GUI then.

Isn't
Ã,  MyModule_btnDoSomething
better? Naming the control for what it does?

Yeah, provided it's prefixed with module name there shouldn't be any name collisions between modules GUI. The original idea is just to try making things consistent when, for example, module owns several GUIs:

MyModule_GUI1_Button1
MyModule_GUI2_Button1
etc...

It's surely possible to give controls different names but still a generic solution would be to have some sort of a prefix (which a GUI name could serve as just well).

But I found another problem with that -- GUI control name can't be longer 25 chars, nor its OnClick function name be longer than 30; so there is a possibility that even module name itself can eat it allÃ, away

Any user that is sophisticated enough to want to publish his own script modules doesn't need a built-in template system. The guidelines and some template text files are enough IMO.

Not a high priority, but still I guess it can be handy that we just started a new module and all the common license info, maybe also VERSION macro would be there. Just like with rooms the editor could probably read from two external text files (if those exist) instead of presenting blank scripts.

[strazer]

Just like with rooms the editor could probably read from two external text files (if those exist) instead of presenting blank scripts.

Yeah, that sounds simple enough. I like it.
Tracker'd: http://www.adventuregamestudio.co.uk/tracker.php?action=detail&id=535

[SSH]

Module name collisions issue

[edit by scorpiorus]

The following quotes were taken from the MODULE: Screenshots SAVELOAD GUI thread:

i imported the modules in the right order and also imported the guis. when i want to test my game i get this error:

'In: savegames with screenshots"

error (line 80): local variable cannot have the same name as an import
how can i fix this?

Do you have your own variable called li?

Change its name to something else

thanks. i really had a variable called "li". but now it works perfectly.

Hmm, interesting. This sort of name collision could happen if you had your own module listed before "Savegames with screenshots" one and which exports a "li" variable which originally is a local variable in "Savegames with screenshots" module itself.

[/edit]

Indeed. I could change the module to have something a bit more obscure, but I'm used to programming languages let local variables MASK any globals, so I think CJ should maybe do something, long term. I guess if ags_freak had stuck all his exports in a struct or with a module prefx, it would be OK.
We should note it in the module writing thread, though.

[Scorpiorus]

Yeah, making a note is a good idea. What I don't like there is no means to catch that one with #ifdefs in implicitly dependent module to display a user-friendly (heh) error message. The ultimate solution would be a possibility to specify what modules (if any) your module depends on. Currently a module depends on each module above (ie. it gets their script headers included).

[SSH]

I noticed while doing the module, btw, that there's was no point in using protected when writing the module: just hide any local function and variables in an struct that inherits the "public" struct. It also effectively allows protected static functions, etc.

[Scorpiorus]

Good point, thanks for sharing! Think it should also be noted in guidelines.

It won't always work for modules that expose structs for further instantiations in user script but for modules that use a single struct as an interface to their functionalities (almost always the case) it looks rather neat.

[SSH]

Hint for module developers:

When I am developing modules, I often use GUI labels to display debug info and trace script stuff. This can be dangerous, as twice I have accidentally left the debug code in which breaks it for everyone else, as they don't have those gui labels.

So, how to solve it? Create a Module at the top of you rmodule list called Debug or something. In the header define DEBUG_MYMODULE and then put #ifdef DEBUG_MYMODULE around all your debug code in your module-under-development. That way, even if you export the module with it all in, no-one else gets the debug stuff and it will work!

Yay!

[strazer]

I think you can even use #ifdef to check for the GUI name the labels are on:

#ifdef GUINAMETHELABELSAREON

But it's not fool-proof as the user could also have a view with this name and then the code would be compiled too. But nice anyway.

[Kweepa]

Before release, I'd recommend importing it into a clean test game to make sure it works.
That way you don't have to remember to put #ifdefs around test code. Speeds up the debugging process.

[Scorpiorus]

Agree with all those bits. I'd do #define-#ifdef approach if I needed the same source code for the debug and release versions of the module. Doing a clean new game test is also a good check to see if it works properly (ie. no undefined tokens etc).

[SSH]

Some further thoughts:

If you want a module to call a user-defined function, how about making a default function in your module but surrounded by:

#ifndef CUSTOM_FUNCTION
#endif

then the user can put their own function in an earlier module and put in a #define to override your module's function.

This could also allow some of a module to be source-protected but some editable...

And finally, I think that the MIT licence is better for AGS modules that LGPL, after some thought:

Code: ags

// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to 
// deal in the Software without restriction, including without limitation the
// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
// sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in 
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 
// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
// DEALINGS IN THE SOFTWARE.

[strazer]

SSH, why do you think the MIT license is better suited? I'm not well versed in legalese...

Also, I'm interested in this:

I noticed while doing the module, btw, that there's was no point in using protected when writing the module: just hide any local function and variables in an struct that inherits the "public" struct. It also effectively allows protected static functions, etc.

I don't quite understand what you mean. Could you elaborate a bit?


Anyway, I've noticed that the length of our discussions and the documents themselves seems to have made people reluctant to release their modules in fear of violating these guidelines.

And I agree the perceived amount of rules seems quite high at first. That's why I've written a short, easy-to-read summary of the guidelines that will hopefully encourage more people to release their modules.

Tell me what you think.

[SSH]

Looks good, great stuff strazer, and I think I agree with your changes.

I prefer MIT, because LGPL insists that any changed versions of the module need to be republishes as open-source, and if someone needs to modify one of my modules to add something game-specific, I don't think that is necessary. MIT simply asks for Credit and denies warranty liability.

I agree about people being scared too. I suggest your summary is made the only post ina locked sticky, with another thread (the rest of this one) linked to for discussion and fuller detail. It should also be presented as "Suggestion" and clearly stated that we'd rather people published modules "as is" than not at all.

[Scorpiorus]

Good work, strazer! Thanks for summing it up

*1 Is it really necessary to restrict the maximum length to 16 characters?

No, I believe... Still, developers should probably be encouraged to use relatively short but yet informative enough names. The problem with really long names is that it may bloat the source code making it a bit difficult to read.

*2 If both utility and application functions have local scope, do we really need to make the distinction?

I think it's up to the author and how they prefer to organize the internal structure of their modules. In this case it's a layered fashion where all functions divided into two or more groups forming layers so that if a higher layer is changed it won't affect a lower one. Again, in my opinion it's up to their decision. Generally depends on how complex the module is.

concerning naming convention for GUIs:

*3 This is my idea, I don't think we reached a consensus yet? What do you think?

I don't really know what's the best approach here. In my opinion, just make sure a GUI name is unique with prefixing it with a module name. But "g" will also be added infront, just to mention.

A shortcup name might be handy though, to compensate for the limit on max length of names.

*4 e moved to front to avoid value names popping up when typing the module name

Personally, I don't mind their popping up and prefer to see all module related stuff on the list but since one may find it annoying and we also have the exact behaviour with GUI names ("g" infront), it may be the option too.

I noticed while doing the module, btw, that there's was no point in using protected when writing the module: just hide any local function and variables in an struct that inherits the "public" struct. It also effectively allows protected static functions, etc.

I don't quite understand what you mean. Could you elaborate a bit?

What I believe he means is:

module header:

struct MyModule {

   // user functions
   import static void DoWork();
};


module script:

struct Internal extends MyModule {

   // additional internal functions
   import static void do_this();
   import static void do_that();
};

Maybe handy sometimes. See his module as an example of usage.

[strazer]

Thanks guys!

I prefer MIT, because LGPL insists that any changed versions of the module need to be republishes as open-source, and if someone needs to modify one of my modules to add something game-specific, I don't think that is necessary. MIT simply asks for Credit and denies warranty liability.

That makes sense. I like that better, too.

I suggest your summary is made the only post ina locked sticky, with another thread (the rest of this one) linked to for discussion and fuller detail.

Good idea, will do once we agree on all points.

It should also be presented as "Suggestion" and clearly stated that we'd rather people published modules "as is" than not at all.

Yeah, I'll emphasize this more.

Still, developers should probably be encouraged to use relatively short but yet informative enough names. The problem with really long names is that it may bloat the source code making it a bit difficult to read.

Sure, I meant to ask if there's a technical reason for the 16 character limit.
I'll change "as short as possible" to "as short but as descriptive as possible".

I think it's up to the author and how they prefer to organize the internal structure of their modules.

I understand the reasoning for the distinction but I agree with you that this should be up to the module author. For consistency, let's suggest lowercase for module-script-only functions?
--Edit:
Hm, come to think of it, since functions can be accessed from anywhere in the script after their definition, maybe camel notation would be the consistent thing?
--

In my opinion, just make sure a GUI name is unique with prefixing it with a module name. But "g" will also be added infront, just to mention.

The reason I proposed the numbering is that (last I checked) GUI names can only be 14 characters long, so with the module name prefix there wouldn't be much left anyway for a descriptive name.

Personally, I don't mind their popping up and prefer to see all module related stuff on the list but since one may find it annoying and we also have the exact behaviour with GUI names ("g" infront), it may be the option too.

Glad you approve.

What I believe he means is:

Great, thanks for clearing that up for me!

[Scorpiorus]

For consistency, let's suggest lowercase for module-script-only functions?
--Edit:
Hm, come to think of it, since functions can be accessed from anywhere in the script after their definition, maybe camel notation would be the consistent thing?
--

My opinion would be to leave it up to the develovers, as long as it relates to module internals. The user functions should however be in camel notation, just to be consistent with AGS built-in ones. But even that should not be that important in contrast to prefixing exposed stuff with module name to avoid name collision.

The reason I proposed the numbering is that (last I checked) GUI names can only be 14 characters long, so with the module name prefix there wouldn't be much left anyway for a descriptive name.

Yeah, I remember there was/is an issue. Any numbers as well as any other names should be ok... provided there is a prefix there. Developer may decide what method to use taking into account the length of module/gui name.

Great, thanks for clearing that up for me!

No problem, thinking of it more however suggests "extends" is not really necessary there since we don't operate with pointers (except for those built-in) to interfaces and such stuff in AGS (at the momentÃ, at least ).

[strazer]

My opinion would be to leave it up to the develovers, as long as it relates to module internals.

Any numbers as well as any other names should be ok... provided there is a prefix there. Developer may decide what method to use taking into account the length of module/gui name.

Of course, the developer is free to do as he chooses. Nobody forces him to follow these guidelines.
Remember, they are only suggestions, but they should be consistent in themselves.

Let's leave it at that. I'll change the suggestion to camel notation.

[Scorpiorus]

Sure. What I just want to point out is that suggestions can be separated in two levels of importance.

First is of a greater importance where it is highly recommended to have a module name prefix to avoid name collisions so that it won't be the reason why one can't have two or more modules working together. It is the reason of having modules after all.

Other is of less one; includes naming conventions, internal organizations etc. May be essential if a group of developers is working on the project, so all would have the same style and it would be easier to read others' codes.

And consistency is a good thing of course

[strazer]

True, important points should probably be emphasized. I'll get on it.

Edit: Done.

[Scorpiorus]

Looks accented now, well done!

By the way, looking at the unique name suggestion what do you think of having a list of modules with their short(script) names included?

A list from AGS Wiki is nice when you're looking for a module to use but it's not clear where it's a script name and where -- a full descriptive one.

I understand, not all modules have a name to prefix but specifying which names are actually "reserved" (already used) would be nice.

It would be of great help to developers, so they wouldn't have to download and open each module to check for its name (if any).

And where should such information be suitably posted?
Possibly as another part of this post?

[strazer]

It think it's a good idea.
But I for one wouldn't want to maintain such a list and I imagine no one else would, so I think adding each module's "script-o-name" to the list of modules in the wiki would probably be the best solution.

In fact, since in the wiki there's hardly any information on the modules anyway, why not just list them all by their script-o-name where available?
Either that, or adding the script-o-name separately without making it look like a mess.

[Scorpiorus]

so I think adding each module's "script-o-name" to the list of modules in the wiki would probably be the best solution.

What I guess may be an obstacle is that some of them reserve additional names for GUIs, etc. I believe it might be too messy to list all such names there.

In fact, since in the wiki there's hardly any information on the modules anyway, why not just list them all by their script-o-name where available?

One problem I see, it's sometimes hard to distinguish between script and full names. The Easy3D module, for instance. That's how it's refered to on Wiki. But the script name is E3d, which is fine for scripting but would look rather ambiguous on the list.

The same goes to "Save/load game GUI with screenshots"; its "sgs" acronym would not look informative at all.


I volunteer myself for looking through the modules to investigate the situation and see if I can come up with a list of used names.
If I manage to compile something I'll post it here for us to consider the rest.

I wouldn't find maintaining the list a big deal but it would be cool if module authors post all the global names (prefixes) they're used in their module thread.

[SSH]

I always meant to expand on the modules list in the wiki, at least for my own modules, and put some documentation in, but haven't got around to it yet....

[Scorpiorus]

Ok, so I took a list of modules from Wiki and browsed through them to see what module "script names" and GUI names are used there, then analysed and built a list.

I didn't check for names of GUI controls at the moment, though.

What I noticed is that some modules have #defined constants (and/or enums) in their headers that could have been prefixed, that would effectively put them within a module "namespace".

Next, there are modules that use an uppercased version of their prefix to define the version macro, ie. MYMODULE_VERSION instead of MyModule_VERSION. It's not a big deal but since the compiler would distinguish between them I listed both.

Also, there are extra prefixes in a couple of modules to mark identifiers (ie. whether it's a struct/function/define). Again, shouldn't be a big chance of name collisions this way but unlike with enums I'm not really sure whether it's necessary.

By the way, another advantage of using the same module name prefix for all identifiers is that once it's typed-in the autocompleter will bring the list of identifiers related to this module. If there is a name one don't want to pop up, then just hide it with #define, $AUTOCOMPLETEIGNORE$, etc...

In either way, those are suggestions aimed to assist users, so that it would be easy to install a module and use, no matter how much code they've written or how many (which) modules are already on the list.

You can find the list here (the list is removed).

[Wretched]

 Thought I might suggest adding a Object/Character Properties naming convention, guess MyModule_Property would do.

[strazer]

Ah, you mean the built-in custom properties accessible from the editor? Sounds like a good idea to me. What do the others think?

[SSH]

Well, in practice I've found those things to be more trobule than they are worth, strazer. But why MyModule? Or is this for properties that are to be used by a module?

[strazer]

Yes, that's my understanding. Apparently his Easy3D module uses custom character properties.

[RickJ]

I just saw Strazer's summary of the Script Module Guidelines.  He has done a nice job of simplifying everything and making it less intimidating.   I have a few comments I'll share below. 

GUI Naming Convention
I have mixed feelings about this proposal.  I understand the motivation behind using the module name as a GUI prefix but wonder if this is the best approach.   

When a Gui event occurs an event handler function is called and passed a pointer to the gui contol that generated the event.   The event handler calls one or more functions to service the event.   In our case here these functions are presumably defined in a module.  The passed pointer is the linkage between the GUI and the module and it can be used to access the GUI and all of it's controls.  It doesn't seem right to uneccessarily create other linkages.

The problem is that the pointers to all controls on all GUIs are global instead of being children of the GUI in which they occur.   So for example if a GUI has two or more labels you can walk through all the controls and pick out all the labels but you don't have a way of knowing which one is which.  If they were children of the GUI then you would be able to get to the one you wanted just by using the child's name (i.e. GuiPointer.Title.Text="Hello").   In this way external references to controls are relative to a GUI which is passed in as a pointer.  The module could then check for the existance of the Title label, in this example, write the title text if the label exists, and do nothing otherwise.   

Hopefully the above description is clear enough to generate some discussion about this.  I have only recently started doing some Module/GUI work so I'm a bit naieve about some of the practicalities but it seems to me that the passed pointer should be the linkage to the GUI and that a method needs to be devised to allow specifc controls relative to the GUI to be identified.   Most of the time the only thing you need to know is the control that generated the event.  In cases where this is inadequate, perhaps, there could be an initialization method where each control on each GUI could be indentified to the module by calling MyModule.GuiInit(GUI *GuiPtr, GUIControl *CtrPtr, int Id).   Something like this:

Code: ags

function game_start() {
   // Initialize Save Game GUI
   MyModule.GuiInit(gSave, gSaveOk, eMyModule_OK);
   MyModule.GuiInit(gSave, gSaveCancel, eMyModule_CANCEL);
   MyModule.GuiInit(gSave, gSaveList, eMyModule_SAVEDGAMES);
}

One other thing relating to GUI naming conventions.  I don't really see any useful purpose in using M$'s infamous hungarian notation (is  that what it's called? i.e.  lblTitle) in forming control names.   In the context of AGS and autocomplete it's redundant to include the data type in the name and it burns up a limited number of characters available to the name.    I suppose everyone has their own preference; mine would be to not encourage the use of this style of notation.   IMHO, it's more important to prepend the GUI name so as to make the most of the auto-complete feature.   Given this, and our use of camel notation everywhere else, this kind of prefix is just out of place and should not really be incouraged.   

What do the rest of you think about this?   

[strazer]

I just saw Strazer's summary of the Script Module Guidelines.  He has done a nice job of simplifying everything and making it less intimidating.

Thanks, I'm glad you approve.

The problem is that the pointers to all controls on all GUIs are global instead of being children of the GUI in which they occur.   So for example if a GUI has two or more labels you can walk through all the controls and pick out all the labels but you don't have a way of knowing which one is which.

I'm not sure I understand what you're suggesting.
I proposed to also enumerate the GUI name when prefixing the module name, i.e. naming the GUI for example MYMODULE1, so you would be able to distinguish labels on different GUIs by prepended the GUI name they're on: MYMODULE1_LabelA vs MYMODULE2_LabelA

If they were children of the GUI then you would be able to get to the one you wanted just by using the child's name (i.e. GuiPointer.Title.Text="Hello").

Is this a feature request or what are you saying?

I don't really see any useful purpose in using M$'s infamous hungarian notation (is  that what it's called? i.e.  lblTitle) in forming control names.

As you say, it's personal preference, my preference in this case. I like all button control names to pop up when I start typing "btn".
But if you read it again, you'll see the control name itself is not part of the suggestion, just a name I chose without thinking. I've changed it now.

[SSH]

I've posted in the Tech Forum about this, but I've moved my preference for licences from the MIT one to the Creative Commons Attribution-Sharealike. One good thing about it is that there are many localised versions of it for your own countries' legal systems.

[strazer]

Yes, I like CC, the licenses are worded so even I can understand.

Is everybody okay with changing our suggested license to this?

This work is licensed under the Creative Commons Attribution-Share Alike 3.0 License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative Commons, 543 Howard Street, 5th Floor, San Francisco, California, 94105, USA.

You are free:
    * to Share â€" to copy, distribute and transmit the work
    * to Remix â€" to adapt the work

Under the following conditions:
    * Attribution. You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work).
    * Share Alike. If you alter, transform, or build upon this work, you may distribute the resulting work only under the same, similar or a compatible license.
    * For any reuse or distribution, you must make clear to others the license terms of this work. The best way to do this is with a link to this web page.
    * Any of the above conditions can be waived if you get permission from the copyright holder.
    * Nothing in this license impairs or restricts the author's moral rights.

And another thing:

I volunteer myself for looking through the modules to investigate the situation and see if I can come up with a list of used names.
If I manage to compile something I'll post it here for us to consider the rest.

I see you haven't updated the list in a while.
As I have feared from the beginning, with the amount of modules being released nowadays, collating these names has probably become more work for one person to handle.
How about we add a "List of reserved module keywords" or something to the Wiki so everybody can help? Would you mind setting that up?

I wouldn't find maintaining the list a big deal but it would be cool if module authors post all the global names (prefixes) they're used in their module thread.

Yeah, another suggestion for authors to update the list probably wouldn't hurt.

[Scorpiorus]

Is everybody okay with changing our suggested license to this?

Yeah, they of course can choose whatever license they like, but that suggested license seems like a good alternative in case they are not sure.

I see you haven't updated the list in a while. As I have feared from the beginning, with the amount of modules being released nowadays, collating these names has probably become more work for one person to handle.

Ah yes sorry that the list hasn't been updated; their quantity is not a real problem though. The real issue is that quite a few modules just doesn't follow the guidelines which makes it questionable whether it's worth listing all the names from a module header.

And listing only those that follow? Seems a bit discriminative to me...

How about we add a "List of reserved module keywords" or something to the Wiki so everybody can help? Would you mind setting that up?

Sure, that's probably the best way to deal with it. I wouldn't use the word keywords, as it more implies some basic language tokens, such as if, while, int etc.

And maybe indeed only put those there that at least use a struct (or prefix) to group their user functions, because that list is more for developers to check if their module's identifiers chance to collide with others'.

[GarageGothic]

But what would the "share alike" clause mean for games using the modules? Does it mean they need to be open source? Does it mean they can't be sold? Simplicity isn't always the same as clarity

[Scorpiorus]

Hmm... I think the main question is what's meant by "build upon this work"?

If a game using a module is considered to be built upon this module then yes the game must also use a similar license.

The problem with script modules is that they are plain source script codes. Were they external compiled units there wouldn't be any problem I believe. A game then would just use the module but it would not be an internal part of the game.

[GarageGothic]

I think share-alike is messy, messy, messy in this context. For instance, few people would allow derivative works of their finished games, whereas a module MUST allow derivative works - already there a share-alike license would be impossible. As I see it, pretty much the only creative commons licenses relevant to modules would be "attribution" and "noncommercial" or not depending on the author's wishes.

[Scorpiorus]

Yep, there is an issue with deriving vs referencing. Conceptually a game just needs to reference a module, but technically it must be derived from it. Worst of all you can make it derived but say it references or make it reference but say it's derived, in regards to computer field.

So what license to suggest do we actually want?

- anyone should be able to use a module in anyway they like (modify, alter, any derivative work)

- but copyrights for the original module itself should stay intact (they may not just change the author's name to their one and re-release it). They may alter the module, change the author name, but then they must make it clear it is a different version(new module?) to the original one.

What else?


EDIT:

On the contrary, the MIT license itself seems a bit too liberal as it not only permits to distribute and publish but even allows to sell the module alone:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

I doubt it will ever happen (unless as a part of the game, but that's another story), but still wanted to mention it to be strict enough.

[strazer]

Okay, so unless we can agree on a more suitable license I say let's just leave it at MIT for now.

Ah yes sorry that the list hasn't been updated; their quantity is not a real problem though. The real issue is that quite a few modules just doesn't follow the guidelines which makes it questionable whether it's worth listing all the names from a module header.

And listing only those that follow? Seems a bit discriminative to me...

I see. Well, if it were up to me alone, I would just ditch the list.
Too much work for too little gain IMO. I don't get the feeling anyone really uses it and I think even a Wiki page wouldn't see many updates.

What do you guys think?

[SSH]

Well, the Wiki category exists, so really any new modules should get their own wiki page and then have the category added: http://americangirlscouts.org/agswiki/Category:Modules

[strazer]

Not sure what you're getting at. We're talking about the list of already-used names, prefixes etc. that Scorpiorus had compiled.

Of course every module could have its reserved names listed on its Wiki page but who would bother clicking through all these module pages if you just want to know if the name you have in mind is already used or not?
We need them listed together on a single page, if at all.

[SSH]

Oh, I see... well, you could perhaps still do it through the wiki, though: some kind of template

[Scorpiorus]

Okay, so unless we can agree on a more suitable license I say let's just leave it at MIT for now.

Ok then, at least the MIT license doesn't restrict the use of a module. We'll see if we can come up with a more suitable license to suggest in the future.

I see. Well, if it were up to me alone, I would just ditch the list.
Too much work for too little gain IMO. I don't get the feeling anyone really uses it and I think even a Wiki page wouldn't see many updates.

I have the same feeling about it. But on the other hand, were I writing a module, I would then look through some of the existing modules that follow up the guidelines to check their prefixes and make sure mine doesn't match any of them (or at least doesn't match those modules with a completely different functionality, as then there is a greater chance they both may be needed for the same game). So having a list of certain modules would be beneficial to me.

Anyway I think I'll remove the list for now. Still, the Wiki page may be a good alternative as it can be contributed to by other module developers. Ah and yeah, it then should be a single page with all the module prefixes to make it easier for developers to look for a certain name.

EDIT:

Done with removing the list!

[monkey0506]

Personally I just make sure I have a unique name for my module and then prefix all my variables (aside from function parameters :o) (including my local variables) with the module's name. It's a good way to help make sure your variables won't collide with another module's. But the list of prefixes and things is nice.

[Scorpiorus]

Personally I just make sure I have a unique name for my module and then prefix all my variables

Yeah, but as more and more modules appear it becomes quite a challenge to look through all of them for the names being used; being reasonably picky you need to download each module and look into their script headers, since module prefix may be different to its full name or a module can use some extra reserved names.

So any module developer that follow up the guidelines would need the list of reserved names (prefixes) one way or another.