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
= 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/
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/
ythonic: