[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 11:37:02 -0400

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
__________�

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