[BlindRUG] Are some naming convention more screen-reader friendly than others?

Fri Jun 9 02:05:52 UTC 2017

Hello Henrik,

I find snake case slower, harder to parse and annoying as a consequence.

I agree with Robin that runinglotsofwordstogether is very irritating to unpick, but I thought that would be true for sighted people too. (Sorry, I couldn't help myself!)

I do not think any screen reader can unpick snake case at this point in time. That doesn't mean it is not possible, but I've not seen how to achieve your idea of using lowered pitch.

With respect to JAWS: the scripting language used for altering the behaviour of JAWS in different applications relies heavily on use of camel case so that means camel case has needed to be well supported by JAWS itself. In effect, JAWS separates camel case strings into words separated by space. NVDA handles camel case in similar fashion.

Turning to indentation: We can ask to be told about indentation when we set the software application settings for configuring our screen reader. This is perhaps only really used by blind people who do lots of programming though. I set  this going in Notepad and Notepad++ for example. Yes, I am told how many spaces is each indent (if that is different to the line I move from)  and occasionally that is "mixed white space" so someone used the tab key instead of the space bar. <sigh>

I hope that helps.
Jonathan

 -----Original Message-----
From: BlindRUG [mailto:blindrug-bounces at nfbnet.org] On Behalf Of Henrik Bengtsson via BlindRUG
Sent: Friday, 9 June 2017 1:02 p.m.
To: Blind R Users Group
Cc: Henrik Bengtsson
Subject: Re: [BlindRUG] Are some naming convention more screen-reader friendly than others?

Thanks for your feedback and sorry for my slow follow-up - this is very helpful.  The fact that upper-case letters can have a different pitch is interesting - I learned something new.

I've got some clarification questions:

Jonathan, you wrote "[dot] and [underscore] ... leads to audible clutter so the snake case is probably the worst of the options you present".  So, words concatenated with dot and underscore are read in a similar fashion, but because the word "underscore" has more syllables, it adds more relative clutter.  Is that correct?  Does the clutter make it harder to parse, requires more concentration, slows you down, or is just annoying?

You say the screen reader can be configured to recognize camelCase constructs and have upper-case letters be read with a higher pitch.
I'm curious, is the configuration powerful enough to have it read out snake_case constructs in two words "snake" and "case" and have the "underscore" not be read per se but instead cause the following letter be read with, say, a deeper pitch?

Robin, you wrote "the main thing to avoid is the concatenation of words in lower case, which is very difficult to read".  Do you mean concatenation of words without dots or underscores making the words just one long sequence of letters that the screen reader won't recognize as separate words?

You also wrote "I find correct indentation very useful when reading other people's code".  How are screen readers providing information about the amount of indentiation?  Does it easily convey the difference between a line with two-space and line with four-space indentation?  Or are you talking about Braille here?

Cheers,

Henrik

On Thu, May 11, 2017 at 1:18 PM, Williams, Robin via BlindRUG <blindrug at nfbnet.org> wrote:
> Hi Henrik,
>
> I largely agree with Jonathan. Personally I prefer the camel case style, although at my place of work where I am frequently sharing code with others the snake case is often also used. As Jonathan says, the main thing to avoid is the concatenation of words in lower case, which is very difficult to read.
>
> Personally I find the indentation of code very useful, despite the slight annoyance of white space at the left hand side of the line. I find correct indentation very useful when reading other people's code, particularly when several commands are nested. It helps me to keep track of the current level of nesting, and I struggle more if code is not properly indented. This is one of the advantageous features of Python, where correct indentation is required by default.
>
> Thanks and best wishes,
> Robin
>
> -----Original Message-----
> From: BlindRUG [mailto:blindrug-bounces at nfbnet.org] On Behalf Of 
> Godfrey, Jonathan via BlindRUG
> Sent: 10 May 2017 20:24
> To: Blind R Users Group
> Cc: Godfrey, Jonathan
> Subject: Re: [BlindRUG] Are some naming convention more screen-reader friendly than others?
>
> Thanks Henrik for taking an interest in our needs.
>
> As someone who primarily works in sound with a braille display as a support tool, I am quite happy to answer the screen reader question, but others might note their individual experiences with the outcome in braille.
>
> The punctuation marks get read aloud by screen readers, so the "." is read aloud as either "period" or "dot" and may differ in the context (middle of a word as against moving the cursor onto the "." itself) and "_"  as "underline" or "underscore". This leads to audible clutter so the snake case is probably the worst of the options you present. You are correct that concatenating lower case words together is even worse and is to be avoided at all cost.
>
> Camel case (with initial letter upper or lower) reads well in sound as 
> the screen readers I use (NVDA and JAWS) both read the words as if 
> they were separated by spaces. This is why I use Camel case in the 
> BrailleR package. I also tend to capitalise the initial letter to 
> denote that the function is from BrailleR as against base R commands. 
> I adjust my screen reader to have capital letters read at a much high 
> pitch  when I move the cursor over them. The standard setting for this 
> is good but  I recommend making it more pronounced. (OK, slightly bad 
> pun)
>
> I'm now using the "." as a means of forcing a function to be internal to the package because it isn't exported by the BrailleR namespace and for the methods in the package. I do not use it for anything else at all. Personally, I'd love the base R language to evolve to remove the use of the "." in functions that are not part of a method, but that's nothing to do with my needs as a blind person.
>
> Braille will be different for each of us and will depend heavily on which braille code we employ. I choose to use computer braille because I do want to see the wider range of characters represented in a single braille cell that is only possible through use of the 8 dots as against a 6 dot literary braille code that takes two cells for capital letters and many brackets used frequently in coding.
>
> I do use tab completion more and more at the command line and would encourage others to start using it if they aren't already.
>
> As for formatting code, you'll know that I used to give little attention to this. Following a discussion with you at UseR last year, and the presentation I saw there to help re-format the code I had, I've tried to keep my code visually cleaner. I'm probably not so consistent and the style of collaborators doesn't always match my own. The amount of white space at the left of code lines can be annoying in braille and sound, but use of the right screen reader settings to announce indenting changes does alleviate this a little. I think it's a smaller problem than having commands too heavily nested and other difficult coding practices though.
>
> Cheers,
> Jonathan
>
>
>
> -----Original Message-----
> From: BlindRUG [mailto:blindrug-bounces at nfbnet.org] On Behalf Of 
> Henrik Bengtsson via BlindRUG
> Sent: Thursday, 11 May 2017 6:54 a.m.
> To: blindrug at nfbnet.org
> Cc: Henrik Bengtsson
> Subject: [BlindRUG] Are some naming convention more screen-reader friendly than others?
>
> Hi.
>
> as a non-screen reader user, I've got a question about coding style and naming conventions for users of screen readers (possibly also Braille readers).
>
> In R there a few different naming conventions are used.  The classical one uses lower-case letters with words separated by periods, e.g.
> read.table().  Closely related to this one is the snake-case style, where lower-case words are separated by underscores, e.g.
> file_path_as_absolute().  BTW, the snake-case style was not possible to do in R a decade ago, because underscore was a reserved symbol and was not allowed in variable and function names.  This was a legacy from S and may explain why the period was used so frequently.
> A third common style in R is the camel-case style where the individual words are identified by capitalizing the first letter (except for the first word), and without a separator, e.g. readLines().
>
> For legacy reasons, I'm a long-term follower of the camel-case style, but I've been considering moving to the snake-case style for many years now.  Knowing where one is better than the other for screen-reader users may help me in this decision.  Maybe it's less about one style versus another, but rather a matter of just using a consistent style throughout, or?
>
> My first question is, for R developers and R end users that rely on screen readers, is there a preference to any of the above styles?  I can imagine that a screen reader could have problems with camel-case names when reading code, e.g. it tries to read them out as one long unknown garbled word, or as an initialism, rather than separate words.
> For instance, does screen reader help distinguish between the following three cases:
>
>   1. my.awesome.function()
>
>   2. my_awesome_function()
>
>   3. myAwesomeFunction()
>
> Second, at the R prompt, is one style easier to use than the others?
> Does it matter when using screen readers, or is the issue the same as I, as a sighted user, have when I don't know the convention and I end up using trial and error with some help from TAB completions?
>
> Finally, does the naming style matter when programming in an editor?
>
> Thanks,
>
> Henrik
>
> _______________________________________________
> BlindRUG mailing list
> BlindRUG at nfbnet.org
> http://nfbnet.org/mailman/listinfo/blindrug_nfbnet.org
> To unsubscribe, change your list options or get your account info for BlindRUG:
> http://nfbnet.org/mailman/options/blindrug_nfbnet.org/a.j.godfrey%40ma
> ssey.ac.nz
> The list archive can be viewed at:
> http://www.nfbnet.org/pipermail/blindrug_nfbnet.org
> More information and useful links about using R as a blind person can be obtained at:
> http://R-Resources.massey.ac.nz
>
> Look for help using R commands by reading the accessible e-book "Let's Use R Now" compiled by Jonathan Godfrey at:
> http://R-Resources.massey.ac.nz/lurn/front.html
>
> _______________________________________________
> BlindRUG mailing list
> BlindRUG at nfbnet.org
> http://nfbnet.org/mailman/listinfo/blindrug_nfbnet.org
> To unsubscribe, change your list options or get your account info for BlindRUG:
> http://nfbnet.org/mailman/options/blindrug_nfbnet.org/r.m.williams%40e
> xeter.ac.uk
> The list archive can be viewed at:
> http://www.nfbnet.org/pipermail/blindrug_nfbnet.org
> More information and useful links about using R as a blind person can be obtained at:
> http://R-Resources.massey.ac.nz
>
> Look for help using R commands by reading the accessible e-book "Let's Use R Now" compiled by Jonathan Godfrey at:
> http://R-Resources.massey.ac.nz/lurn/front.html
>
> _______________________________________________
> BlindRUG mailing list
> BlindRUG at nfbnet.org
> http://nfbnet.org/mailman/listinfo/blindrug_nfbnet.org
> To unsubscribe, change your list options or get your account info for BlindRUG:
> http://nfbnet.org/mailman/options/blindrug_nfbnet.org/henrik.bengtsson
> %40gmail.com
> The list archive can be viewed at:
> http://www.nfbnet.org/pipermail/blindrug_nfbnet.org
> More information and useful links about using R as a blind person can be obtained at:
> http://R-Resources.massey.ac.nz
>
> Look for help using R commands by reading the accessible e-book "Let's Use R Now" compiled by Jonathan Godfrey at:
> http://R-Resources.massey.ac.nz/lurn/front.html

_______________________________________________
BlindRUG mailing list
BlindRUG at nfbnet.org
http://nfbnet.org/mailman/listinfo/blindrug_nfbnet.org
To unsubscribe, change your list options or get your account info for BlindRUG:
http://nfbnet.org/mailman/options/blindrug_nfbnet.org/a.j.godfrey%40massey.ac.nz
The list archive can be viewed at:
http://www.nfbnet.org/pipermail/blindrug_nfbnet.org
More information and useful links about using R as a blind person can be obtained at:
http://R-Resources.massey.ac.nz

Look for help using R commands by reading the accessible e-book "Let's Use R Now" compiled by Jonathan Godfrey at:
http://R-Resources.massey.ac.nz/lurn/front.html