Functions - how far to go with them?

[csda1]

Re: Functions - how far to go with them?

Hi Robert,

Does anyone have any suggestions for naming conventions for functions and code?

I have been taking code off of buttons lately and I end up with a long list of code that is becoming unmanageable. Sometimes the hardest part of writing a new piece of code is choosing the name for it.

See Cal's Naming Conventions tips. Cal and I differ a bit in our naming conventions, but it's a good start. Basically I'd say make it unique, 23 or less characters, be clear to it's purpose, don't end in a number, Don't start with something similar to many Alpha function names, and if for distribution, include unique ID in name to avoid name collisions, e.g. AIMS_Format, CSDA_BarCode.

I also tend to make test code start with "a_" to put it at the top of the code list. When I am done with old code, I tend to rename it, starting it with "z_" (and occasionally adding a number at the end to indicate version revision) so it sorts to the bottom of the code list.

It looks like I will be converting my code to UDFs from now on as per the good advice of this thread, but how do you deal with all the new code that is generated that used to be hidden in button events and other places?

In general, if it's a 1 line piece of code (e.g. Opening a form), leave it in the button/event (I'll use the term button below to mean ervent code). If it's a small conditional, e.g.

IF date()>{01/01/2000}
 newdate=myfunction(birthdate)
ELSE
newdate=myfunction(addyears(birthdate,-1))
END IF

then put the conditional in the function. If the reference date is different, pass it as a parameter argument, e.g.

newdate=myfunction(birthdate,{01/01/2000})

that calls the same function 2 different ways. You could either possibly add an end parameter (ideally optional and/or having a default), or use an existing function parameter to control the choice.

However, assuming it couldn't be brought into your function, something as simple as the above I would still leave in the button.

It comes down to what constitutes code specific to the use on the button (in which case it tends to stay on the button), and what is common between other uses of similar code (in which case it goes in the function). Once the button's code exceeds a trivial # of lines (particularly if I need to debug/edit it alot, or think about what it is doing at the higher level concept, it goes to a function)

One exception to this is the OnKey event. Sometimes this is very time sensitive, if you have poorly written code. The number of key events is a lot higher than one might think. So the top of the code does a check to see if it is what I need to process. If not, it immediately returns. If it is, it calls my onkey code that I have in a function. That code tends to amount to maybe 5 lines of code.

From another perspective, consider the fact that my common library of functions has roughly 1000 functions in it that I have written over many years. Many are test code or old versions. That is not a lot, and none of the finished ones are similar. So it is not every button, it is just my "common code"

[Mayapur]

Re: Functions - how far to go with them?

Thanks Ira for your tips. I didn't know that Cal had added a small section on naming functions. I have tried to follow his recommendations since I first read them.

I am finding that if I start each button code name with the form name things seem a bit more organized and easier to find.

[Mike Wilson]

Re: Functions - how far to go with them?

I have to chime in just because I have been questioning the naming convention for function ever since I have converted to using them so extensively. I think this is a good topic and I would like to hear some mindful opinions on this.

Not having the answer by any means, I will share what I have migrated to. LATIN. Not that I chose to do this intentionally, but I recognized the other day that what I have migrated to and have been become quite comfortable with is the format of SUBJECT_CHARACTERISTICS/DESCRIPTOR_VERB. And it came to me that this is the sentence structure of LATIN. One very common function that I generate is for low-to-high complexity sorting. An example is one I am working on today. A portfolio and financial management application. The function I named - Positons_type_sort(). Positions=table;Type= Sort field parameter(stock, mutual funds, bonds, etc.); sort= verb/action. This name declares to me what this function's "pursuit" is about. And that is what I believe a functions name should deliver...

Although the naming of some function do not always resolve clearly to have a definitive second parameter, and therefore I don't include it, I have been able to ascribe and assign most to fall somewhere under these three, and able to name the functions with this convention, and found it reliable, systematic, and very helpful.

Given that, under my system: table.external_record_content_get(), one of my high use functions, in my system would be: table_fieldvalue_list().

From my mind.... what are your thoughts?

[csda1]

Re: Functions - how far to go with them?

Hi Mike,

That's a reasonable approach. Just looking at my function library, some names include

Barcode_C128
Barcode_C93
Geo_Query
Geo_Zip

which kind of follow your format.

[MikeC]

Re: Functions - how far to go with them?

I think most who try to organize anything will agree in principal with your method Mike....another way of looking at it is to go from General to Specific in the function/script name. And I generally try to limit the name to three short terms as well at most...sometimes only two suffice and most times three can be used to distinguish between many similar functions very well.

Another aspect to consider is whether to start the name to become part of Alpha's naming scheme to bring up the UDF along with similar built-in ones or to bring up what you know are UDFs only....several ways to do the latter.

But making sure, of course, that any name that is chosen is not something that Alpha may come up with in the future is important too.

[SMARTII]

Re: Functions - how far to go with them?

General Rules:
1. When in doubt make it a function.
2. Make the function with at least 1 or 2 argument(s) even if you don't use them immediately. Adding a parameter or argument place later makes a mess of places you used the function already, especially in several places. You have to change them all, if you can remember where you have them.

As for scripts, you can always add a local function inside it later on to make it more generic.

[CALocklin]

Re: Functions - how far to go with them?

Building on Mike's comments in post #18, here's something that I read a long time ago....

The advice was to start your script/function names with either a noun or a verb but NEVER do both. If you do one or the other, then you always know where to look. If you mix them, then you don't know whether to start looking under "Print" or "Work_order" to find the routine that will print work orders.

The preference was to start with a noun. If you use a verb, as many people tend to do, you will end up with a large number of names that start with something like Get_, Print_, etc. By using a noun instead, the groupings will probably be smaller and they can also be grouped according to the part of the application you are working on.

For example, if you are doing something with work orders your names might start with "Wo_". Now you can look for Wo_ and quickly determine if you have a Wo_Print routine, Wo_Lookup routine, Wo_email_cust, Wo_email_group, etc. If these were grouped by the verb (action), then you would have to jump all over the code tab trying to figure out what had been done for dealing with work orders.

And, think about those last two names. If the code was grouped under the verb, the "email" routines for everything would be grouped together and Email_group_wo could be quite a few items away from Email_cust_wo. They might be separated by Email routines for action items, projects, customers, and who knows what else. (Yes, it would help if you changed the names to Email_wo_xxx but I'm trying to make a point here!)

[jkletrovets]

Re: Functions - how far to go with them?

FWIW....I follow the methodology Mike and Cal mention for naming my functions. It works well - you can quickly do your own mental and visual "Lightning Query Optimization" in your brain to quickly find stuff in the Control Panel. :D

Posted by Ira - One exception to this is the OnKey event. Sometimes this is very time sensitive, if you have poorly written code. The number of key events is a lot higher than one might think. So the top of the code does a check to see if it is what I need to process. If not, it immediately returns. If it is, it calls my onkey code that I have in a function. That code tends to amount to maybe 5 lines of code.

Ira can you explain this a tad further? I have an onkey event that calls a function to reset some variables and then resets an embedded browse on a form to a default set of records. This might work great 15 times in a row then....not so much. :)

In my attempt to isoloate this, I have made the onkey event into a function and then it calls a function. Code is below:


OnKey Event:

WO_OnKey()

Funtion it calls is pretty much straight from the help file onkey event(the xbasic wait for idle and ui_yield were attemps to solve the inconsistency I am seeing):

FUNCTION WO_OnKey AS C ( )
 If (A_USER.KEY.VALUE = "{^W}") then
   If (A_USER.KEY.EVENT = "down") then
        ' Reset Screen to default settings
         WO_MgmtReset()
         xbasic_wait_for_idle()
         ui_yield()
         vsearchwo.activate()
   End if
End if
END FUNCTION

Thanks

[csda1]

Re: Functions - how far to go with them?

Hi Tom,

2. Make the function with at least 1 or 2 argument(s) even if you don't use them immediately. Adding a parameter or argument place later makes a mess of places you used the function already, especially in several places. You have to change them all, if you can remember where you have them.

The above implies that you are not aware that function parameters (at least the trailing ones) can be optional. E.g. if you have a function definition like

FUNCTION functionname as C (parameter1="ABC" as C, parameter2=0 as N, parameter3=DATE() as D)

All of these calls are acceptable

functionname("DEF", 4, (01/02/2009}) ' Uses "DEF", 4, (01/02/2009}
functionname("DEF", 4) ' Uses "DEF", 4, DATE()
functionname("DEF") ' Uses "DEF", 0, DATE()
functionname() ' Uses "ABC", 0, DATE()

Each unspecified trailing parameter has a default definition if not included. Alpha Five does not allow skipped parameters (although some languages do :(), such as

functionname("DEF", ,(01/02/2009})

Thus if you add a new parameter at the end, the 1st ones should still work. This also means that choosing the parameters to use and the order of parameters at the initial creation of the function is helpful, as you don't have to fix their usage later. This often ends up being an iterative process during initial creation. It is seldom that I go back and change the order. If you do need to, consider using A5DOC or AIMS App Analyzer or CSDA Code Utility (current version searches all functions & scripts - next version adds searches (with 10x increased speed) of operations, menus and toolbars) to find usages to fix.

Most of my functions have a parameter called Flags (other popular names that others use for the parameter might be options, switches, settings) that allow various characters (1 or more of them) to allow different ways of using the same function. (A bad alternative, IMHO, is when people have a bunch of logical flag parameters beyond 1 or 2). This allows expansion beyond what I originally intended for a function. I try to be consistent in the use of some letters, e.g.

Q - Quiet (no UI)
X - Close modeless dialog boxes if previously opened by function
H - Help
? - Help
V - Version and date of code
M - Modal or Modeless UI (depends on function as to which it means)
T - Test Mode
Z - Diagnostic Mode (dumps more info)
@ - For functions enhancing Alpha's built-in functions, this calls Alpha's function with the equivalent parameters for testing and comparison.

Some combinations of letters have no meaning, or some letters have precedence over other. Case of the flags is generally ignored. In general, no order of the letters is relevant. Some letters ignore some of the parameters as well. I try to leave numbers 0->9 to being flags having a numeric meaning.

[csda1]

Re: Functions - how far to go with them?

Hi Jeff,

Ira can you explain this a tad further? I have an onkey event that calls a function to reset some variables and then resets an embedded browse on a form to a default set of records. This might work great 15 times in a row then....not so much. :)

Let me clarify one point. I'm not saying it fails, just that it slows key handling down that it looks like the keyboard is operating slowly.

Thus, I would modify your code like this

OnKey Event:

If .not.(A_USER.KEY.EVENT = "down") then
     end ' very quick return for up strokes
 END IF
If .not.(A_USER.KEY.VALUE = "{^W}") then
    end '' very quick return if not keys we need to process further
END IF
WO_OnKey()

Function

FUNCTION WO_OnKey AS C ( )
' We repeat this code for good measure It just makes sure the code works even
' if you forgot to put it in the ONKEY event code.  A good example of redundant 
' programming to catch errors.  e.g. test for <0 and =0 implies anything left should 
' be >0, but sometimes you miss a subtle difference, so you explicitly code the 
' other option.  There is a 4th value in Alpha called MATH_NAN (null number) that 
' sometimes appears.
If .not.(A_USER.KEY.EVENT = "down") then
     exit function ' very quick return for up strokes
  END IF
If .not.(A_USER.KEY.VALUE = "{^W}") then
    exit function '' very quick return if not keys we need to process further
END IF

' I never saw you actually specify that you handled the key, as shown in next line
a_user.key.handled=.T.
 
' Reset Screen to default settings
WO_MgmtReset()

' I believe putting UI_Yield 1st works better (or actually works).  The other way 
' seems to cause more issues.  If possible eliminate one or both of the UI_YIELD() 
' and XBASIC_WAIT_FOR_IDLE()
ui_yield()
xbasic_wait_for_idle()

vsearchwo.activate()

END FUNCTION

[jkletrovets]

Re: Functions - how far to go with them?

Ira,

Thank you for the explanation and the code! It is nice to see code from someone as accomplished as yourself. I'll implement these changes you provided and report back.

Thanks again...

Jeff