5 Replies Latest reply on Mar 23, 2016 4:30 AM by alecgregory

    Parameters in standard script commenting




      I used to comment my script using an introduction line and then commenting each block of code in the script. It works relatively well as we are only two working on the solutions at the moment.

      However, I might need to work with more people in the future so I decided to start using the standard way of commenting script which can be found here: http://filemakerstandards.org/display/cs/Commenting



      # ===================================================================

      # Purpose: Describe the purpose of the script [short version]

      # Parameters: one ; two ; three

      # ---------------------------

      # $one = (enum) load, unload

      # $two = (string) second parameter

      # $three = (num) expected

      # ---------------------------

      # Called From: (script) any

      # Author: Matt Petrowsky

      # Notes: Additional information [long version]

      # Revision: Last change: 10/10/10 by MP :: A single comment step with multiple lines

      # ===================================================================



      My problem is that I don't really understand what "Parameters" are. Are they script parameters or all the variables used in the script?

      And also, what does "called from: (script) any" means? Does it mean that it is not called by any script, like a script fired only from a button?


      Thank you!



        • 1. Re: Parameters in standard script commenting

          I would say that Parameters and Called From can mean anything you like them to mean.

          Use them for whatever you want.

          Seems like the intent is to describe any and all data that can get passed into the script via script parameters or accessed by the script via global variables.

          Called From seems like it would be a list of any script that calls the script.

          Called From does not seem to be very useful IMHO.

          • 2. Re: Parameters in standard script commenting
            Markus Schneider

            one can call a script and send one or more parameters (at the bottom of the window where the script s defined)


            often, parameters are defined in another way, ie the caller-script defines some $- or $$-Variables (scriptstep 'set variable'. There are many ways to set variables (not just within a script, further on, some FM developer are using global fields as well)


            IMHO, a parameter is something that has to be already defined for the target script - it's needed, therefore it makes sense to note the header-comments

            • 3. Re: Parameters in standard script commenting

              Thanks both!


              I use script parameters a lot but almost never in the form of variables, that's why I was confused. It makes sense for a parameter appearing in the header to be already defined elsewhere and not something you will define as a variable further away in the script.

              • 4. Re: Parameters in standard script commenting

                Hi Chloe,


                I don't use this script commenting standard but I take Parameters to mean any script parameters being passed to the current script. Call From I assume to be the name of a parent script that calls the current script as a subscript.


                That's just my assumptions but makes sense to me :-)




                • 5. Re: Parameters in standard script commenting

                  I would say that Parameters and Called From can mean anything you like them to mean.

                  Use them for whatever you want.

                  Up to a point, yes, do whatever helps you as a developer deliver what you need to deliver.


                  But a large part of using standards is to learn to do things in a way that is understood by other developers who also use the same standards (or indeed yourself a few years/months/seconds later). So User26869 is right to seek the generally understood meaning of Parameters and Called From.




                  My understanding is that Parameters should refer only to the parameters passed directly to the script and accessed via Get ( ScriptParameter ). When there is more than one script parameter, an effective way to pass the parameters is using Name Value pairs, described in the standards site here and supported by Custom Functions. There are other methods such as return-separated, which can be done more easily without Custom Functions.


                  This follows the lead of other programming languages where parameters are seen as much more important than internal variables and therefore advertised and explained more widely in documentation. It's very common for internal variables to be completely absent from documentation.


                  Called From


                  I believe Called From is intended to list all the launch possibilities for the script, not just other scripts that call it. So a more extensive example would be:


                  # Called From:

                  #   (script) Script One

                  #   (script) Script Two

                  #   (script) Script Three

                  #   (menu) Actions > Function

                  #   (layout) Invoices > "New" Button

                  The idea is to document how extensively the script is used in your solution so that you and other developers know where they have to make changes if, for example, the required parameters for this script change.


                  Called From does not seem to be very useful IMHO.


                  It's hamstrung by the fact that you need to manually update the places where the script is called from. I've found it hard to remember to do this and therefore rarely end up with a comprehensive list. However, if properly maintained, it is very useful for keeping track of where a script is called without needing to run a DDR.


                  It would be great if standards could have a dedicated "Place" in this community. I've learnt a lot from filemakerstandards.org, but I think the standards effort in general needs to be far more visible than it is currently. This would have the dual benefits of involving a greater number of developers in building FileMaker development standards/best practices and making standards more widely known to developers just starting out.