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

Thu May 11 20:18:56 UTC 2017

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