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

Fri Jun 9 01:02:23 UTC 2017

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%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
>
> _______________________________________________
> 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%40exeter.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