[jawsscripts] Re: Variable naming in scripting, was Re: Re: JAWS scripts how I did the trial example

  • From: Doug Lee <doug.lee@xxxxxxxxxxxxxxxx>
  • To: jawsscripts@xxxxxxxxxxxxx
  • Date: Tue, 11 Jun 2013 14:31:06 -0400

Ah yes, I meant to mention that this idea of declare-on-demand instead
of declare-at-top is not possible in all languages. Truth be told, I
learned the concept from seeing a lot of Javascript doing it this way.
Prior to that, having come through C, C++, Pascal and a bit of Delphi,
and the myriad JAWS scripts that declare at top, I was used to
declaring all variables in one place. What changed my tune was the
following set of realizations:

1. It can be harder to know what a variable is for when it's declared
early and used late.

2. It's easier to use one variable twice accidentally if you declare
it at the top in a long code block.

3. If you accidentally declare a variable twice in JAWS, you get a
compile error. This actually reduces the chances of the above
scenario. For example, if I have a loop near the top that uses
variable "i," and another loop occurs later where I try to use "i"
again but make the mistake of assuming it starts at 0, the second loop
will quietly fail if I declare "i" at the top, whereas if I put "var
int i" (or better, "var int i = 0") before each loop, the compiler
will catch me in the declare-on-demand approach, so I can either
explicitly set i=0 or use a new variable name.

4. Somewhat similarly, typos can sometimes be caught by
declare-on-demand, though this may happen rarely in practice: If I use
iCurPos as an index in an early loop and "i" in a later one, but out
of typing habits I type "i = i +1" instead of "iCurPos = iCurPos +1"
at the end of the first loop, the declare-on-demand approach will
cause the compiler to catch me, since I will not have declared "i"
yet. This has actually happened to me, though not often.

I should point out that I do not personally like to do every last
possible thing to make the compiler catch my mistakes. My favorite
example: People who write "if 0 == iTypeCode" do it because it will
cause a compiler error if they mistype it as "if 0 = iTypeCode" (one =
sign instead of two). That is of course a nasty little error because
it can otherwise be hard to spot, but I so hate seeing the line
backward that I just don't do it anyway. :-)

On Tue, Jun 11, 2013 at 11:53:44AM -0700, John Martyn wrote:
When declaring variables, say you have a long list of codiditional
statements. Usually I do code clean up and put the variables at the top
because it seems funny to me that variables can be declared later in the
script and be used before the declaration. If you did this in PHP you would
throw an error.
John

-----Original Message-----
From: jawsscripts-bounce@xxxxxxxxxxxxx
[mailto:jawsscripts-bounce@xxxxxxxxxxxxx] On Behalf Of Doug Lee
Sent: Tuesday, June 11, 2013 8:37 AM
To: jawsscripts@xxxxxxxxxxxxx
Subject: [jawsscripts] Re: Variable naming in scripting, was Re: Re: JAWS
scripts how I did the trial example

My preferences, which apply to all programming languages I've worked with,
including JAWS scripting and Python:

Indent code as sighted people do, because it helps communication with them
and sometimes helps me trace my own logic later.

Use Tab, not spaces, to indent, to minimize keystrokes and chances for
errors, e.g., if you use four spaces per indent level and type three spaces
once, it may look a bit odd but you're likely not to know it.
Tab also lets people choose how deep the indents appear by changing tab stop
distances in some environments. Tabs also replace nicely with spaces at the
last minute for those who want it that way.

I don't use type prefixes very often, but I do wait to declare a variable
until right when I first need it, instead of declaring 15 variables at the
top of a function.

I use a blank line between functions/scripts and between major sections of
code within one sometimes, and sometimes I use two blank lines between major
sections of a file. I use fences (===, ---, ***,
etc.) pretty much only when a sighted colleague really wants that. I do use
fences in JAWS scripts to separate what I call code modules within one
script file.

I comment a script or function below, not above, its definition line, so F2
and downArrows nicely let me skim summaries of an entire file of code.

I rarely comment after code on the same line, though I think I do it
sometimes. Rather, I usually comment on a line above the code being
commented upon.

Just my approach to all this...

On Tue, Jun 11, 2013 at 07:25:57AM -0800, Soronel Haetir wrote:
I wonder if it is a matter of how much code someone is used to dealing with.

Especially if someone were used to dealing with HTML instead of programming
code I could see there being an aversion to indentation or other unneeded
whitespace.

Like I said, when dealing with jaws scripts I tend to be much looser about
such things, but the scripts I write tend to be very short (no more than ten
lines for the entire script file is very common for me).
 But when dealing with code bases that run into multiple megabytes I do find
that adhering to much stricter programming style is all but essential.  And
I would say that the turnover point for me is much closer to the ten line
script file than it is to where such is actually needed.

On 6/11/13, Bissett, Tom <tom.bissett@xxxxxxx> wrote:
> This is an interesting thread.
> I use only speech and I don't like indentation.  I find it distracting 
> and of no value to me.  I do need to use it because of shop standards 
> but to me it is just annoying extra work.
> I say it is an interesting thread because it makes me wonder why for 
> some it is helpful and for others it is a distraction.
> Tom Bisset
> -----Original Message-----
> From: jawsscripts-bounce@xxxxxxxxxxxxx 
> [mailto:jawsscripts-bounce@xxxxxxxxxxxxx] On Behalf Of Andrew Hart
> Sent: June 11, 2013 10:16 AM
> To: jawsscripts@xxxxxxxxxxxxx
> Subject: [jawsscripts] Re: Variable naming in scripting, was Re: Re: 
> JAWS scripts how I did the trial example
>
> Ditto.
>
> On 10/06/2013 11:52 PM, Don Mauck wrote:
>> Agreed.
>> -----Original Message-----
>> From: Jim Snowbarger [mailto:Snowman@xxxxxxxxxxxxxxxx]
>> Sent: Monday, June 10, 2013 7:52 PM
>> To: jawsscripts@xxxxxxxxxxxxx
>> Subject: [jawsscripts] Re: Variable naming in scripting, was Re: Re:
>> JAWS scripts how I did the trial example
>>
>> Actually, the thing I find most annoying about the way lots of blind 
>> folks code is the practice of not using indentation.
>> Speech users are most prone to this, because indentation does less 
>> for them, and is also harder to maintain.
>> But, when you are used to it, it is wonderfully instructive.  Braille 
>> users will really appreciate it, and sighted programmers require it.
>> Oh yes, and then there are languages like Python that depend on it.
>> But, when I look at somebody's code that has no indentation structure 
>> to it, I am far more bothered than the way they name their variables, 
>> except for the practice that lots of my sighted colleagues engage in, 
>> where most vowels are omitted.  It can keep you busy creating 
>> dictionary entries, so I just
>> usually put up with it when I must.   But, names that tell you what they
>> are
>> because they speak nicely, are as short as practicable, yet 
>> descriptive, that helps my brain a lot.
>>
>>
>>
>>
>> ----- Original Message -----
>> From: "John Martyn" <johnrobertmartyn@xxxxxxxxx>
>> To: <jawsscripts@xxxxxxxxxxxxx>
>> Sent: Monday, June 10, 2013 12:11 AM
>> Subject: [jawsscripts] Re: Variable naming in scripting, was Re: Re:
>> JAWS scripts how I did the trial example
>>
>>
>> I think the main thing that I do is program like I am still sighted. 
>> I know many languages and still code like it. I guess it is a matter 
>> of preference but it should be practiced, even by me. I get a little 
>> lazy by assigning variants functions instead of creating a function 
>> that has specific return policies. I frequently do this with variants 
>> because I can't waste time making a proper function.
>> John
>>
>> -----Original Message-----
>> From: jawsscripts-bounce@xxxxxxxxxxxxx 
>> [mailto:jawsscripts-bounce@xxxxxxxxxxxxx] On Behalf Of Geoff Chapman
>> Sent: Sunday, June 09, 2013 7:47 PM
>> To: jawsscripts@xxxxxxxxxxxxx
>> Subject: [jawsscripts] Variable naming in scripting, was Re: Re: JAWS 
>> scripts how I did the trial example
>>
>> hahahaha Ok fair enough Jim.
>> I understood and can concur with most of the below, and thanks for 
>> posting your thoughts on this here.
>>
>> I agree with the suffix/prefix thing re comprehension.
>>
>> It's probably only that after reading lots of code with variable type 
>> prefixes to their names, I guess now that I just feel somehow 
>> distinctly disconcerted now when I don't see them. and my brain is 
>> thus puzzling out what that variable might be holding.
>>
>> For more advanced scripters it's probably jolly obvious from the 
>> sense of the code, what variable type is being referred to at any given
moment.
>> It's just that I found the practise reeeally very helpful when I 
>> heard about it initially. and I personally still like to see it.
>>
>> any others thoughts?
>>
>> G.
>> ----- Original Message -----
>> From: "Jim Snowbarger" <Snowman@xxxxxxxxxxxxxxxx>
>> To: <jawsscripts@xxxxxxxxxxxxx>
>> Sent: Monday, June 10, 2013 11:36 AM
>> Subject: [jawsscripts] Re: JAWS scripts how I did the trial example
>>
>>
>>> That's an interesting puzzlement that my good friend Mister she or 
>>> he poses here.  There is certainly no requirement to do this.  While 
>>> it has it's uses, It's not illegitimate to not do it.  Personally, I 
>>> have vascilated on this over the years, and continue to do so even 
>>> now.
>>> Even in my professional environment, folks are divided on this.
>>> Their concern is screen space, mine is information bandwidth, the 
>>> narrow pipe imposed by speech.  On the one hand, yes it does convey 
>>> type and scope, just by looking at the name.  On the other hand, 
>>> most of the time, you don't care about those things. Or, if you do, 
>>> you are familiar enough with the code that you already know that, or 
>>> can easily learn it.
>>>
>>> Mostly, you are reading code to figure out what it does, and hearing 
>>> the same variable mentioned repeatedly with extra syllables 
>>> prepended just takes more time, and slightly increases the mental 
>>> sorting that needs to be done.
>>>
>>> The one exception is, when I declare global variables, I always use 
>>> some special additions, because all globals by all scripts use the 
>>> same name space, and it helps avoid confusion.
>>> But, in that context, I started using suffixes rather than prefixes, 
>>> because I personally found it easier to read.  It seems like the 
>>> concept of, what this actually represents, pops into my brain more 
>>> quickly when I use suffixes, and while eloquence is jabbering the 
>>> suffix, I'm mostly ignoring it, thinking about the quantity this 
>>> thing represents.  Or, if it is something I'm not looking for, I can 
>>> more quicly decide to skip it.
>>> It's
>>> kind of like hearing, check box, checked, before you hear what it is 
>>> that is checked.  Takes you half an hour to decide that whatever it 
>>> is, it's checked, but then realizing, so what, it wasn't what you 
>>> were looking for in the first place.
>>> IF I use a prefix, I have to wait through the prefix before I know 
>>> what the heck we are talking about.
>>> It's kind of like the practice some folks use of writing their, if, 
>>> statements in reverse order.
>>>
>>> if (true == iStatus)
>>> That always twists my head.
>>>
>>> But, anyway, I do have mixed feelings about any unnecessary, extra 
>>> syllables slowing me down when I'm trying to rapidly tool through 
>>> code.  Fewer syllables, the absense of stuff I don't really need to 
>>> know, all these things help my retarded brain focus on the so-called 
>>> important stuff.
>>>
>>>
>>>
>>> ----- Original Message -----
>>> From: "Geoff Chapman" <gch@xxxxxxxxxxxxxxxx>
>>> To: <jawsscripts@xxxxxxxxxxxxx>
>>> Sent: Sunday, June 09, 2013 5:40 AM
>>> Subject: [jawsscripts] Re: JAWS scripts how I did the trial example
>>>
>>>
>>> Hi John. I just have a question I've been wanting to ask you for a 
>>> while?
>>> I
>>> hope you will not be in the least offended by it.
>>> But, it's been puzzling me.
>>>
>>> Is there any reason, in your code, why you kinda seem not to have 
>>> adopted what I understood to be the traditional protocol/FS syntax 
>>> for your variable types? by placing a small case letter connoting 
>>> their type before their Mixed case name? such that one can more 
>>> easily and readily glean their types when puzzling through the code 
>>> itself?
>>> I.e.
>>>
>>> variant vPath,
>>> string sStartDate,
>>> int iRegDay,
>>> Object oXML.dom,
>>>
>>> etc.
>>> And if declaring/using a global, to place a small G before the 
>>> variable type as well?
>>> Of course it's obviously not so relevant to do this at the 
>>> declaration stage, but, man it sure makes it easier for the 
>>> uninitiated when studying raw code I reckon.
>>>
>>> I know it's as clear as mud to the scripter when she/he is doing the 
>>> coding, what variable holds what data, and why, but, in my view, it 
>>> sure makes for more warm/friendly decoding when either another 
>>> person wants to work through the code. Or, I'm also told by the 
>>> master whom you had said initially inspired your scripting talents, 
>>> in 5 years time when you yourself wish to tool back through some 
>>> part of the code for updating or whatever, and the whole deal is no 
>>> longer so fresh in the mind as it was upon initial writing?
>>>
>>>
>>> Thanks for any thoughts.
>>>
>>> G.
>>>
>>> ----- Original Message -----
>>> From: "John Martyn" <johnrobertmartyn@xxxxxxxxx>
>>> To: <jawsscripts@xxxxxxxxxxxxx>
>>> Sent: Sunday, June 09, 2013 6:25 AM
>>> Subject: [jawsscripts] JAWS scripts how I did the trial example
>>>
>>>
>>>> I hope you can all make use of this code. It is not perfect by any 
>>>> means, but it accomplishes what you want.
>>>> This is how I did the trial. The function below can be called from 
>>>> other scripts or functions. Below the function is the PHP date page 
>>>> code that creates an XML page that the script can download to get 
>>>> the date from the server. This relies on an internet connection and 
>>>> a php server. This next lines of code create the XML object.
>>>>
>>>>
>>>>
>>>> let XMLDom = CreateObjectEx ("Microsoft.XMLDOM", 2)
>>>>
>>>> Delay (2, 1)
>>>>
>>>> if !XMLDom then
>>>>
>>>> let XMLDom = CreateObject ("Microsoft.XMLDOM")
>>>>
>>>> endif
>>>>
>>>>
>>>>
>>>> function trial()
>>>>
>>>> var
>>>>
>>>> variant path,
>>>>
>>>> string StartDate,
>>>>
>>>> string currentDate,
>>>>
>>>> int regDay,
>>>>
>>>> int regMonth,
>>>>
>>>> int regYear
>>>>
>>>>
>>>>
>>>> XMLDom.Load("http://www.yourSite.com/date.php";)
>>>>
>>>> ; you need to make the delay so the page can load. The delay
>>>>
>>>> ; is based upon the XMLDom.XML variable if it has populated the 
>>>> cached copy
>>>>
>>>> DelayXML()
>>>>
>>>> let currentDate = XMLDom.SelectNodes("//theNode")
>>>>
>>>> let currentDate = currentDate.item(0).text
>>>>
>>>> if !currentDate then
>>>>
>>>> Say("Your system is not connected to the internet for the trial to 
>>>> continue.
>>>> Please check your connection.",4)
>>>>
>>>> return 0
>>>>
>>>> endif
>>>>
>>>> let path = "SOFTWARE\\SubKey\\AnotherSubKey\\Location"
>>>>
>>>> ;in the registry entry
>>>>
>>>> ;1 is the current user
>>>>
>>>> ;2 is the local machine etc
>>>>
>>>> let startDate = GetRegistryEntryString (1, path, "VariableKeyName")
>>>>
>>>> if !startDate then
>>>>
>>>> SetRegistryEntryString (1, path, "variableKeyName", currentDate)
>>>>
>>>> let startDate = GetRegistryEntryString (1, path, "VariableKeyName")
>>>>
>>>> if !startDate then
>>>>
>>>> Say("Your system does not support this trial software. Please 
>>>> select the purchase option.",4)
>>>>
>>>> return 0
>>>>
>>>> endif
>>>>
>>>> endif
>>>>
>>>>
>>>>
>>>> ;get the registry start date
>>>>
>>>> let regDay = StringToInt (StringSegment (startDate, "/", 1))
>>>>
>>>> let regMonth = StringToInt (StringSegment (startDate, "/", 2))let 
>>>> regYear = StringToInt (StringSegment (startDate, "/", 3))
>>>>
>>>>
>>>>
>>>> ;now find the expiration date
>>>>
>>>> var
>>>>
>>>> variantArray theDayArray,
>>>>
>>>> int theDay,
>>>>
>>>> int theMonth,
>>>>
>>>> int theYear,
>>>>
>>>> int trialPeriod,
>>>>
>>>> int EXPDay,
>>>>
>>>> int EXPMonth,
>>>>
>>>> int EXPYear
>>>>
>>>> ;create an array of the total days in a month
>>>>
>>>> let theDayArray = new variantArray[1,12]
>>>>
>>>> let theDayArray [1,1] = 31
>>>>
>>>> let theDayArray [1,2] = 28
>>>>
>>>> let theDayArray [1,3] = 31
>>>>
>>>> let theDayArray [1,4] = 30
>>>>
>>>> let theDayArray [1,5] = 31
>>>>
>>>> let theDayArray [1,6] = 30
>>>>
>>>> let theDayArray [1,7] = 31
>>>>
>>>> let theDayArray [1,8] = 31
>>>>
>>>> let theDayArray [1,9] = 30
>>>>
>>>> let theDayArray [1,10] = 31
>>>>
>>>> let theDayArray [1,11] = 30
>>>>
>>>> let theDayArray [1,12] = 31
>>>>
>>>>
>>>>
>>>> ;current date
>>>>
>>>> let theDay = StringToInt (StringSegment (currentDate, "/", 1))
>>>>
>>>> let theMonth = StringToInt (StringSegment (currentDate, "/", 2))
>>>>
>>>> let theYear = StringToInt (StringSegment (currentDate, "/", 3))
>>>>
>>>> ;how many days, limited to a month
>>>>
>>>> let trialPeriod = 15
>>>>
>>>>
>>>>
>>>> if regDay+trialPeriod > theDayArray[1,regMonth] then
>>>>
>>>> let EXPDay = (theDayArray[1,regMonth] -regDay)
>>>>
>>>> let EXPDay = (trialPeriod - EXPDay)
>>>>
>>>> let EXPMonth = regMonth+1
>>>>
>>>> if EXPMonth > 12 then
>>>>
>>>> let EXPMonth = 1
>>>>
>>>> let EXPYear = regYear+1
>>>>
>>>> else
>>>>
>>>> let EXPYear = regYear
>>>>
>>>> endif
>>>>
>>>> else
>>>>
>>>> let EXPDay = trialPeriod+regDay
>>>>
>>>> let EXPMonth = regMonth
>>>>
>>>> let EXPYear = regYear
>>>>
>>>> endif
>>>>
>>>>
>>>>
>>>> ;now compare the registry dates to the EXP date
>>>>
>>>> if theYear > EXPYear then
>>>>
>>>> Say("Your trial period has expired. Please purchase the
>>>> software.",4)
>>>>
>>>> return
>>>>
>>>> endif
>>>>
>>>> if theMonth > EXPMonth then
>>>>
>>>> Say("Your trial period has expired. Please purchase the
>>>> software.",4)
>>>>
>>>> return
>>>>
>>>> endif
>>>>
>>>> if theMonth == EXPMonth && theDay > EXPDay then
>>>>
>>>> Say("Your trial period has expired. Please purchase the
>>>> software.",4)
>>>>
>>>> return
>>>>
>>>> endif
>>>>
>>>>
>>>>
>>>> ;trial Still valid
>>>>
>>>> return 1
>>>>
>>>> EndFunction
>>>>
>>>>
>>>>
>>>> Here is the php code:
>>>>
>>>> <?php
>>>>
>>>> //Must make the page refresh each time
>>>>
>>>>                 header( "Cache-Control: no-cache, must-revalidate"
>>>> );
>>>>
>>>>                 header( "Pragma: no-cache" );
>>>>
>>>>
>>>>
>>>> $date = date("d/m/Y");
>>>>
>>>> echo "<?xml version='1.0' encoding='ISO-8859-1'?>";
>>>>
>>>> echo "<rootNode><private>$date</private></rootNode>";
>>>>
>>>> ?>
>>>>
>>>>
>>>>
>>>> Thanks for all the suggestions for this to work. I would like to 
>>>> see some different versions of this code so let me know what you think.
>>>>
>>>> John Martyn
>>>>
>>>>
>>>>
>>>> __________???
>>>>
>>>> View the list's information and change your settings at 
>>>> //www.freelists.org/list/jawsscripts
>>>>
>>>
>>> __________???
>>>
>>> View the list's information and change your settings at 
>>> //www.freelists.org/list/jawsscripts
>>>
>>>
>>>
>>> __________???
>>>
>>> View the list's information and change your settings at 
>>> //www.freelists.org/list/jawsscripts
>>>
>>>
>>
>> __________???
>>
>> View the list's information and change your settings at 
>> //www.freelists.org/list/jawsscripts
>>
>> __________???
>>
>> View the list's information and change your settings at 
>> //www.freelists.org/list/jawsscripts
>>
>>
>>
>> __________???
>>
>> View the list's information and change your settings at 
>> //www.freelists.org/list/jawsscripts
>>
>> __________???
>>
>> View the list's information and change your settings at 
>> //www.freelists.org/list/jawsscripts
>>
>>
>>
>
>
> __________???
>
> View the list's information and change your settings at 
> //www.freelists.org/list/jawsscripts
>
> __________???
>
> View the list's information and change your settings at 
> //www.freelists.org/list/jawsscripts
>
>


--
Soronel Haetir
soronel.haetir@xxxxxxxxx
__________???

View the list's information and change your settings at
//www.freelists.org/list/jawsscripts

--
Doug Lee, Senior Accessibility Programmer SSB BART Group -
Accessibility-on-Demand mailto:doug.lee@xxxxxxxxxxxxxxxx
http://www.ssbbartgroup.com "While they were saying among themselves it
cannot be done, it was done." --Helen Keller __________o?=

View the list's information and change your settings at
//www.freelists.org/list/jawsscripts

__________???

View the list's information and change your settings at 
//www.freelists.org/list/jawsscripts

-- 
Doug Lee, Senior Accessibility Programmer
SSB BART Group - Accessibility-on-Demand
mailto:doug.lee@xxxxxxxxxxxxxxxx  http://www.ssbbartgroup.com
"While they were saying among themselves it cannot be done,
it was done." --Helen Keller
__________�

View the list's information and change your settings at 
//www.freelists.org/list/jawsscripts

Other related posts:

  1. Home
  2. jawsscripts
  3. Archive
  4. 06-2013