Coding Conventions and Speech: No Punctuation, Renaming Operators etc...

  • Thread starter Veli-Pekka Tätilä
  • Start date

V

Veli-Pekka Tätilä

Hi,
I realize this is not the optimal newsgroup for questions like this but
thought I'd give it a shot anyway. That is I'm a sight impaired guy doing
programming mostly as a hobby and have recently found Perl to cut a long
story short. Now, I'm wondering if there are any style guides that would
focus on making the code as easy to read as possible for screen reader
users. I don't intend to distribute my code anywhere just yet so being
friendly to the sighted reader as well is not of primary concern at the
moment. So here are some observations of mine as well as a question or two.
Any and all comments are welcome.

I have a bit of sight left in my left eye but am still primarily a screen
reader user and legally blind, too. Synthetic speech, full-screen
magnification at 5x or more and braile being the primary output media in
this order. Unlike most people I'm not using the Jaws screen reader in
Windows but a British reader and magnifier called Supernova. For the
interested reader, the home of Supernova is:

http://www.dolphinuk.co.uk/

And info on my sight can be found here.

http://www.student.oulu.fi/~vtatila/sight.html

As there are people with varyin levels of sight and having different tastes,
I reckon the use of the screen reader differs quite a bit. One Weakness of
Supernova is that the punctuation levels are preset so you cannot
selectively ignore certain punctuation. Thus it is pretty much a none or all
affair. Setting punctuation to all reads all operators, parentheses and so
on but is tiering to listen to

while($_ = <IN>)

becomes

while left paren dollar underline equals less than in greater than right
paren

Sure you get use to this style of operation and it is the same nuisance with
almost any language apart from, perhaps SQL.

The alternative is to turn punctuation off completely so you get:

while in

This is nicer but heavily ambiguous regarding what operators and variables
are used inside the parentheses. Still it is all right if you are writing
short snippets of code and can recall what certain piece of code ought to be
doing approximately. I've found that comments can help, too. Still I need to
occasionally check some punctuation and tend to do this with magnification
or braille. IT is slow but this method has worked well, so far.

Now I'm basically thinking of what kind of steps could be used to get Perl
code easier and less ambiguous if reading with speech and punctuation set to
none. Here's what I've found out so far although many of these habits
haven't yet caught on in my case and I'm realizing new things when writing
this:

1. It is advisible to get rid of as much punctuation as possible.

a. Leave out parentheses when-ever possible.

b. Use the English module. So in stead of undef we get undef input record
separator. Note the exact spelling as punctuation is not read and case
changes or underlines are taken to be word delimiters.

c. Perl supports and, or and not in stead of the horrible ampersand
ampersand etc... as in C or Java. Use the verbal forms.

d. Learn to use q, qq and qw to represent quotes unambiguously as well as
comment regexp. Verbal character classes read nicer than a-zA-Z.

e. Short loops in which the body becomes before the loop or condition being
tested are preferrable, because you can fit things naturaly on one line and
get rid of redundant braces. Functional programming ala map and grep should
also be encouraged when-ever it fits the problem and can omit braces.

f. Comment ending braces to make it explicit when a block ends. Often I use
the keyword of the condition or loop or the name of the current sub. as in

sub marine
{ # A demonstration function doing nothing at all.
# do stuff
} # marine

Notice the braces. I've never quite gotten into the K&R style of bracing.
One benefit of this left brace on its own line style is that you can attach
short comments naturally as in explaining some condition, decision,
rationale etc...

Still it would be even cooler in my view if you could omit braces
completely. I don't like the Pascal style but Python is not bad in this
regard apart from eval-ing code I guess. So can you get some Perl module
that let's you omit braces or adds them just prior to parsing the program?

2. Naming variables and functions.

a. Many of the Perl language functions sound like natural language which I
like. That is things like die, split and so on. There are some problematic
cases, though. I don't generally like shortenings such as eval or errno as
they sound silly on a speech synth 'e-vul and 'err, no'. Eval is especially
close to evil so for a long long time before using Perl I thought Unix
shells and Perl had an evil function, hehe.

b. On a similar note some operators are problematic, too. Most string ops
are read out nicely but arithmetic is not and must almost always be checked
out with braille, magnification or cursoring in characters using speech.

Is it possible, feasible or easy to redefine some function names in a file
once and include that file to be used in my own scripts? I'm new to modules.
I'm not thinking of renaming many of the built-in functions but arithmetic
would be easier to read with the following mappings (reckon you could do
them as defines in C):
+ plus
* times
/ divided by
% modulo
< less
== equals
= is
... to
and so on
I cannot change the reading of punctuation in the screen reader, at least on
a per app basis.

c. It would be preferrable if the variable name indicated naturally the
type of the variable without having to check the initial sign dollar, at or
percent. One basic way is to use single forms for scalars and plurals or the
suffix list for arrays as in $scalar, @scalars, @scalarList (the last two
are arrays). For hashes things are not as easy. I prefer to name them so
that they indicate the nature of the mapping %keys2values e.g.
%strings2lengths. You can also turn the concept upside down by saying
%valueByKey as in %personById.

d. For references, file handles etc... I still need to think of good
conventions. You can make the readre beep case differences but that soon
gets annoying, too, so upper-case handle names are not automatically
distinguished. Maybe the suffixes File and Dir or some identifier as in
Hungarian notation such as h for handles, and r for references could be
used. I generally dislike Hungarian notation, though, as sometimes word-like
constructs are read as words and at other times not. that is CALLWNDPROC and
HINSTANCE are read as words so it sounds like rubbish (well that's what
Win32 is, only kidding though).

e. As to OOP stuff, which I haven't done in Perl yet but know Java, I like
the prefixes my for object variables and their for class variables.
Sometimes I also use the Epoc-inspired form aParameter in method parameters.
I reckon this is a as in argument but I sometimes also read it as the
article a. AS in we know the actual parameter passed but from the function's
point of view that is just aParameter out of several possible values that
could be passed.

f. I'm all for named arguments using hashes when it makes the code natural
to read. One of the most beautiful examples so far is one I accidentally
found on Larry's site:

move $rook from => $qr_pos, to => "kb3";

This reads out very well using speech even if punctuation is set to none.

3. Other ideas.
a. Though no punctuation is read, certain punctuation characters are implied
by changes in intonation. This is somewhat speech synth dependent but with
Dolphin orpheus v2 the following holds. Comma and colon translate to a short
pause with no change in intonation. This is nice in argument lists and
labels among other things. A question mark raises the pitch slightly so the
question colon operator is hinted at by the speech. The exclamation mark
adds a short pause and lowers the pitch so it could be succesfully used as a
delimiter in tr, m and so on. Finally, this is most likely a long-standing
bug but with the current version of Orpheus a single quote surrounded by
white space (/s) is read out even if punctuation is set to none. I'm not
sure if any uses for this quirk could be found. Maybe to mark comments in
some way.

b. If you hav any ideas on how to make Perl more speech friendly using
modules or coding conventions, I would appreciate your input. I might even
do a style guide that emphasizes ease-of-use with speech. Of course coding
practises like this are merely to make Perl as nice and cosy to code in as
possible at home. For any production code, there's usually a strict style
guide to follow and variation is not permitted.

With kind regards Veli-Pekka Tätilä ([email protected])
Accessibility, game music, synthesizers and programming:
http://www.student.oulu.fi/~vtatila/
 
Ad

Advertisements

A

attn.steven.kuo

Veli-Pekka Tätilä said:
Hi,
I realize this is not the optimal newsgroup for questions like this but
thought I'd give it a shot anyway. That is I'm a sight impaired guy doing
programming mostly as a hobby and have recently found Perl to cut a long
story short. Now, I'm wondering if there are any style guides that would
focus on making the code as easy to read as possible for screen reader
users.

(snipped)


On a similar note some operators are problematic, too. Most string ops
are read out nicely but arithmetic is not and must almost always be checked
out with braille, magnification or cursoring in characters using speech.

Is it possible, feasible or easy to redefine some function names in a file
once and include that file to be used in my own scripts? I'm new to modules.
I'm not thinking of renaming many of the built-in functions but arithmetic
would be easier to read with the following mappings (reckon you could do
them as defines in C):
+ plus
* times
/ divided by
% modulo
< less
== equals
= is
.. to
and so on
I cannot change the reading of punctuation in the screen reader, at leaston
a per app basis.
....



Source filtering may be a way to
go. The Filter::Simple
module is available on CPAN
and should allow you to
replace arthimetic operators
in your code with terms in
a natural language.

For example:


package English_to_Math_Ops;
use Filter::Simple;

FILTER {
s!\s plus \s! + !xg;
s!\s modulo \s! % !xg;
s!\s divided by \s! / !xg;
s!\s times \s! * !xg;
s!\s equals \s! == !xg;
}

1;



use English_to_Math_Ops;

print "foo" if 3 plus 5 equals 8;
 
A

attn.steven.kuo

Veli-Pekka Tätilä wrote:

(snipped)
As there are people with varyin levels of sight and having different tastes,
I reckon the use of the screen reader differs quite a bit. One Weakness of
Supernova is that the punctuation levels are preset so you cannot
selectively ignore certain punctuation. Thus it is pretty much a none or all
affair. Setting punctuation to all reads all operators, parentheses and so
on but is tiering to listen to

while($_ = <IN>)

becomes

while left paren dollar underline equals less than in greater than right
paren



This idiom can be replaced by
the more text-to-speech friendly
and less ambiguous 'readline' function.

$ perl -MO=Deparse -e 'while (readline *IN) { next };'

while (defined($_ = <IN>)) {
next;
}
-e syntax OK


(more snipped)
b. If you hav any ideas on how to make Perl more speech friendly using
modules or coding conventions, I would appreciate your input. I might even
do a style guide that emphasizes ease-of-use with speech. Of course coding
practises like this are merely to make Perl as nice and cosy to code in as
possible at home. For any production code, there's usually a strict style
guide to follow and variation is not permitted.


I have no experience yet with this
module, but after briefly examining its
documentation on CPAN I would venture
that Regexp::English would make
understanding regular expressions,
when spoken, much easier.
 
A

Anno Siegel

Veli-Pekka Tätilä said:
Hi,
I realize this is not the optimal newsgroup for questions like this but
thought I'd give it a shot anyway. That is I'm a sight impaired guy doing
programming mostly as a hobby and have recently found Perl to cut a long
story short. Now, I'm wondering if there are any style guides that would
focus on making the code as easy to read as possible for screen reader
users. I don't intend to distribute my code anywhere just yet so being
friendly to the sighted reader as well is not of primary concern at the
moment.

[Using the screen reader Supernova]
I reckon the use of the screen reader differs quite a bit. One Weakness of
Supernova is that the punctuation levels are preset so you cannot
selectively ignore certain punctuation. Thus it is pretty much a none or all
affair. Setting punctuation to all reads all operators, parentheses and so
on but is tiering to listen to

while($_ = <IN>)

becomes

while left paren dollar underline equals less than in greater than right
paren

You could keep punctuation speaking on and run the text through a filter
that removes unwanted punctuation.

More generally, filtering a Perl source before it is spoken could help
making it more understandable without changing the code itself.

If the code could be analyzed to the level a typical syntax highlighter
does in an editor (not perfect, but usually close), you'd know what are
keywords and what are variables, where blocks begin and end and what
is code, string or comment. With these at hand, it should be possible
to give excellent understanding aids without compromising the source
code itself.

Unfortunately, I have no idea what's involved in prying the syntax
highlighter lose from an editor and making it usable this way. It
would certainly not be done in a day or two.

Anno
 
V

Veli-Pekka Tätilä

Source filtering may be a way to go.
hey, looks like a feasible solution for exactly cases like this.
The Filter::Simple module is available on CPAN
Looking at the docs this appears to be the ideal choice. Now the trouble is
where can I get a pre-compiled PPM binary for Win32? I've only got the
active state default reps set. Snippet of session follows:

ppm> rep
Repositories:
[1] ActiveState PPM2 Repository

[2] ActiveState Package Repository
end of snippet

I've been manually roaming through most of the well-known PPM reps, I think,
but no-one seems to have packaged the Filter::Simple module yet. The heavier
Filter module is in many places but I'd like to avoid it for the time being.
 
V

Veli-Pekka Tätilä

This idiom can be replaced by
the more text-to-speech friendly
and less ambiguous 'readline' function.

$ perl -MO=Deparse -e 'while (readline *IN) { next };'
Ah good old ReadLine. Brings Java to mind though I read the manpage and
things are of course different. The name read-line is sort of poor, though,
if you can set the record separator to something other than the new line
character. Wouldn't the name read_record be more accurate? Not that it
matters that much but just came to mind.
that Regexp::English would make understanding regular expressions,
when spoken, much easier.
It certainly does. I took a look at the docs and found the PPM at
ActiveState's. Though I've always considered regexp so tricky as to be
examined one charactter at a time, this module certainly prsents a far nicer
way of writing them. I'm especially fond of the fact that the quantifiers
are handled as being prefix operators rather than post-fix.

When I began studying regexp for the first time, it took me quite a while to
realize that quantifiers quantified the thing before, and not after, them.
The prefix approach would also appear to emulate natural languages in this
regard. In Finnish and English at least, you usually put the numeral before
the things being counted.

One quick question about this Regexp module, though. I found a method called
match but how do I split or replace using these fancier regular expressions?
Can I feed hese regexp objects to split or s somehow?
 
Ad

Advertisements

V

Veli-Pekka Tätilä

Anno said:
More generally, filtering a Perl source before it is spoken could help
making it more understandable without changing the code itself.
Yes, one problem with a conventional source filter is that once the source
is filtered I reckon there's no easy way to see the filtered end-result, is
there? Again doesn't matter much just yet but I suppose most sighted folks
would prefer to read the ordinary source code, which is valid Perl without
processing.
If the code could be analyzed to the level a typical syntax highlighter
does in an editor (not perfect, but usually close), you'd know what are
keywords and what are variables, where blocks begin and end
That's true though my current editor, NoteTab Pro, does not support Perl
syntax highlighting. Of course the highlight info would need to be
represented textually. COlors just make the text harder to read by lowering
the contrast and my sight is not good enough for quickly distinguishing
between a number of colors.

And with screen reader prompts, you might well get something like:
color blue $variable color green equals color red 7 to give an imaginary
example. That is hardly neither compact nor very informative. Should I deal
with pre-defined color names in the code, things will be even messier.

That's why, you guessed it, I don't let the screen reader prompt foreground
color changes and try to generally disable syntax highlighting when-ever
easily possible.
would certainly not be done in a day or two.
Yep and I would probably need to move on using some Unix editor like VI or
Emacs. I've got nothing against them as such but the accessibility of most
console programs using a Windows screen reader is not terribly good compared
to native Win32 controls.

Still an interesting tac of solving the problem. Thought provoking stuff.
 
A

Anno Siegel

Veli-Pekka Tätilä said:
Yes, one problem with a conventional source filter is that once the source
is filtered I reckon there's no easy way to see the filtered end-result, is
there?

I'm not particularly acquainted with the filter modules, but I'm sure
there is.
Again doesn't matter much just yet but I suppose most sighted folks
would prefer to read the ordinary source code, which is valid Perl without
processing.

That's one problem I see with the source filter approach. It would be
preferable to leave the source code alone as much as possible and add
reading aids only as it goes to the screen reader.
That's true though my current editor, NoteTab Pro, does not support Perl
syntax highlighting. Of course the highlight info would need to be
represented textually. COlors just make the text harder to read by lowering
the contrast and my sight is not good enough for quickly distinguishing
between a number of colors.

Oh, I didn't mean to use syntax highlighting as it comes. It's a
pain on the eyes even for people with normal eyesight -- I usually
switch it off if I don't have time to tune it.
And with screen reader prompts, you might well get something like:
color blue $variable color green equals color red 7 to give an imaginary
example. That is hardly neither compact nor very informative. Should I deal
with pre-defined color names in the code, things will be even messier.

Sure, that would be no help at all.

What I mean is, use the info a typical syntax analyzer has to change
symbols to meaningful strings. If you know that a certain "{" begins
a new block, you could render it as "begin block", or even "begin block
level N". "$", "@" and "%" could be translated to "scalar", "array" and
"hash" if they come before a variable, but to "dollar", "at-sign" and
"percent" in comments and strings. That kind of thing.

I suppose, only a fraction of what a syntax analyzer "knows" can
be usefully rendered in speech. Wise limitation would be the key.
That's why, you guessed it, I don't let the screen reader prompt foreground
color changes and try to generally disable syntax highlighting when-ever
easily possible.

Sure, the visual aids a syntax highlighter produces are no help for the
blind, and reading them aloud would presumably make things worse. One
would have to find ways of producing textual aids that work in an auditory
environment. Even with the syntax analysis out of the way that would have
to be a sophisticated program.

Anno
 
V

Veli-Pekka Tätilä

Abigail said:
Filter::Simple has been part of the main Perl distribution since 5.8.0.
Umm how can I have missed it. I must confess I often don't use Perldoc but
look in the HTML sub-directory manually. Perl reports:

perl -v
This is perl, v5.8.6 built for MSWin32-x86-multi-thread
(with 3 registered patches, see perl -V for more detail)
<snipped the rest>

OK it seems I should have the module. LEt's see ...
C:\Perl\html\lib\Filter\
How can I have missed this. I dunno. MAybe the fact that there are docs
under both .\site\lib and .\lib, assuming the HTML dir to be the current
directory, is part of the equation.
Furthermore, Filter::Simple is written in pure Perl, so there's no need
for a precompiled version - there's nothing to precompile.
Ah silly me. I bet you're all tired of these newbie questions. I guess I
must have been thinking of Java and PYthon having read somewhere that Perl
uses some sort of virtual machine internally and optimizes the code before
running. I was further confused by the fact that some Win32 modules do
require compiling but now I realize that's because they're talking in C to
the WIn32 API. A bit like native code in Java then, isn't it?
 
V

Veli-Pekka Tätilä

Anno said:
I'm not particularly acquainted with the filter modules, but I'm sure
there is.
Quite right. Perusing the HTMl docs yields the following note in
Acme::pythonic:
the Filter::ExtractSource manpage can be used to inspect the source code
generated by Acme::pythonic:

perl -c -MFilter::ExtractSource pythonic_script.pl
Acme::pythonic itself has a debug flag though:

use Acme::pythonic debug => 1;
In debug mode the module prints to standard output the code it has
preferable to leave the source code alone as much as possible and add
reading aids only as it goes to the
screen reader.
Yep, too bad the screen reader is closed source and does not support
scripting. The leading reader app called JAws has Support for app-specific
totally custom punctuation and Supernova's lack of this has been cursed by
some programmers for a good reason. I bet the Gnome reader Gnopernicus is
not any better, though. I briefly tried it out on a Debian system I had. I
like that Gnopernicus stays true to the original screen contents but as far
as I know doesn't have that much control over things, especially on a per
app basis.
Oh, I didn't mean to use syntax highlighting as it comes.
OK misunderstanding cleared.
usually switch it off if I don't have time to tune it.
Speaking of syntax highlighting on an OT:ish side-note, I don't like the one
in Visual Studio 6 the least bit. The only way of turning it off Ive found,
is to manually go through each and every darn color setting and tell it to
use the system colors.
What I mean is, use the info a typical syntax analyzer has to change
symbols to meaningful strings.
Sounds reasonable but rather difficult. A simple solution would be to use
the exception dictionary for the screen reader for primitive replacements.
You can let it match whole words, substrings and at start or end of word.
The trouble is if the exceptions are on, I'll get the same Perlish meanings
in every app then. In nethack an exclamation mark is quite different from
Perl, let alone an ordinary sentence, so the term exclamation remains
general enough.

Another tac would be to use sound effects for variable type, for instance,
but the readre only let's you attach them to case changes currently. I'm in
beta testing and have suggested the option be generalized, however.
begin block level N". "$", "@"
That sounds good. If you can figure out the context I would shorten the
prompt a bit to something like begin n or even n begin if the level is the
most relevant thing. But these things come down to taste and that's why many
screen readres have fairly customizable prompts already. I can change the
prompt for spinners (spinnable lists) to cycle gadgets if I want to.
and "%" could be translated to "scalar", "array" and
"hash" if they come before a variable, but to "dollar", "at-sign" and
"percent" in comments and strings. That kind of thing.
GOod that you are pointing out the context, hadn't thought of it in that
great a detail. DOllar is also used in dereferencing and braces can denote
an anonymous hash reference.
I suppose, only a fraction of what a syntax analyzer "knows" can
be usefully rendered in speech.
Depends I say. A good bases would be to think of how one would like the
source code read out loud by a human being first. You could then drop some
of the finest contextual differences if they seem overly difficult to
implement.

Example:

for(my $i = 0; $i < $max; ++$i)

could well be read out something like:

for my i 0, i less than max, plus plus i.

Here scalarness, assignment and parentheses would be implied and you could
take short pauses between semicolons. That's how i read absolute paths, too:
implying the dir separator by a short pause and droping colons or a leading
double back-slash in UNC names.

You'll usually get things left to right and one word at a time as speech is
what I call a linear medium (another name is straw analogy: as if you were
looking at the screen contents through a straw). Direction is almost always
left to right, too, though there are things that read out more naturaly
right to left or starting from the inner-most parentheses.
 
Ad

Advertisements

V

Veli-Pekka Tätilä

Abigail said:
Veli-Pekka Tätilä ([email protected]) wrote on MMMMCCCLIII
September MCMXCIII in <URL:news:[email protected]>:
Wow that sounds whacky with a speech synth <smile>. I mean passages like
MCMXCIII and MMMMCCCLIII that are read as words with a quivering pitch for
some reason.
can your screen reader be tuned so it doesn't read text where the
foreground and the background colours are the same?
you can (mis)use syntax highlighting by giving the punctuation you
don't want to see the same fore- and background colours.

A good question and an interesting idea, too. As far as I know that's not
possible and I'm also using magnification so it would decrease readability.

From what I know of Supernova's inner-workings it uses systemw-wide Win32
hooks, Active Accessibility and a kernel-mode (?) Screen interception driver
to get at Windows internals and messages. Recognizing fonts is not based on
optical character recognition but it can get them as text (usually window
text, I guess). Actually, it is also able to redraw true type fonts larger
when using magnification features.

Getting the font as text means that even if I set text size to 1 it will
still get it quite right. However, window edges can clip text for some
reason.
 
Ad

Advertisements


Top