Style questions
As a blind person, I have to listen to code. As such, I've developed
habits that make it easier for me to do that. But I am wondering if
other people are going to hate my style.
-
I always use what I think is called camel notation for identifiers.
For example, thisIsaFunctionName. A screen reader is going to read that
"this isa function name". If you write taht this_isa_function_name, it
says "this underscore isa underscore function underscore name". -
I use a single tab instead of multiple spaces. The reason this is
better to listen to is that the screen reader just says "tab" for one
tab and "tab tab" for 2 tabs. If you're using 4 spaces, it has say
either "space space space space" or "4 spaces".
3. I put a comment after a close brace to say what it is closing. For
example, the brace to close a for loop I'll write "} // rof".
- I put the opening brace for a code group on a separate line. That way
it lines up with the close brace (which I've commented).
How annoying is this stuff?
John,
Code formatting can be a highly (hotly-debated) personal issue. For my
$0.02 I'd say that I wouldn't have any serious issues processing your
code. The tabs might work on my OCD as this is how we (sighted folks) make
the code more readable. The handling of tabs hasn't gotten much attention
until recently. Many editors are now making some effort at formatting code
WRT braces and this effort is promising, but it still is a ways off from
being able to hit a button and have the editor format all the indentations
for you and get it right every time.
Of course, your dilemma trumps our (sighted folks) inconvenience. I'd say
you are covered if you include a comment at the top of your code that
states "This code is formatted for blind readers" or better words to that
effect. If anyone wants to tilt at that windmill they would be a special
kind of stupid in my opinion. Given a disclaimer as to the nature of the
code formatting, I'd happily accept that I'd need to deal with the odd
appearance, or I'd have to put some effort into reformatting if my OCD
pressures me to do so.
Cheers,
Joe
On Thu, Aug 18, 2022 at 2:32 PM John Heim sconnie.johnnie@gmail.com wrote:
As a blind person, I have to listen to code. As such, I've developed
habits that make it easier for me to do that. But I am wondering if
other people are going to hate my style.
-
I always use what I think is called camel notation for identifiers.
For example, thisIsaFunctionName. A screen reader is going to read that
"this isa function name". If you write taht this_isa_function_name, it
says "this underscore isa underscore function underscore name". -
I use a single tab instead of multiple spaces. The reason this is
better to listen to is that the screen reader just says "tab" for one
tab and "tab tab" for 2 tabs. If you're using 4 spaces, it has say
either "space space space space" or "4 spaces". -
I put a comment after a close brace to say what it is closing. For
example, the brace to close a for loop I'll write "} // rof". -
I put the opening brace for a code group on a separate line. That way
it lines up with the close brace (which I've commented).
How annoying is this stuff?
OpenSCAD mailing list
To unsubscribe send an email to discuss-leave@lists.openscad.org
Camel case is probably used by nearly 50% of coders, so nothing unusual there. Useful info about how screen readers handle it, though. I write math/science content for visually impaired audiences using openscad code, so I'll definitely keep that in mind.
I can't stand people who use spaces instead of tabs. There will be people on the other side of that argument, but again, it means you're not outside the norm.
I've seen people comment their closing braces before. I don't consider it worth my effort, but I admit that it's probably good practice. I might balk at being asked to do it (especially in OpenSCAD, where you'd have to do it a lot), but I don't think anyone would have a problem with seeing it done in someone else's code.
Putting the opening brace on its own line is another one that religious wars are fought over. I personally side with K&R style, which puts it at the end of the previous line, but I've seen lots of code with it on its own line. So again, nothing unusual, and you won't get into any more fights about it than any sighted coder would.
On Aug 18, 2022, 12:32 -0700, John Heim sconnie.johnnie@gmail.com, wrote:
As a blind person, I have to listen to code. As such, I've developed
habits that make it easier for me to do that. But I am wondering if
other people are going to hate my style.
-
I always use what I think is called camel notation for identifiers.
For example, thisIsaFunctionName. A screen reader is going to read that
"this isa function name". If you write taht this_isa_function_name, it
says "this underscore isa underscore function underscore name". -
I use a single tab instead of multiple spaces. The reason this is
better to listen to is that the screen reader just says "tab" for one
tab and "tab tab" for 2 tabs. If you're using 4 spaces, it has say
either "space space space space" or "4 spaces".
3. I put a comment after a close brace to say what it is closing. For
example, the brace to close a for loop I'll write "} // rof".
- I put the opening brace for a code group on a separate line. That way
it lines up with the close brace (which I've commented).
How annoying is this stuff?
OpenSCAD mailing list
To unsubscribe send an email to discuss-leave@lists.openscad.org
On 8/18/2022 12:32 PM, John Heim wrote:
As a blind person, I have to listen to code. As such, I've developed
habits that make it easier for me to do that. But I am wondering if
other people are going to hate my style.
Speaking for myself: Hate? Definitely not. Disagree with? Maybe, mildly.
- I always use what I think is called camel notation for identifiers.
For example, thisIsaFunctionName. A screen reader is going to read
that "this isa function name". If you write taht
this_isa_function_name, it says "this underscore isa underscore
function underscore name".
No strong feeling. Mostly, I use a "when in Rome, do as the Romans do"
approach. If I'm modifying something that uses camelCase, I'll use
camelCase - notably usually including an initial capital for a class
name. One problem comes when camelCase collides with other conventions
that put constants in all upper case. Visually distinguishing constants
from variables seems useful, but once it's in all upper case of course
you can't use camelCase to mark the words.
Left to myself, when I'm not paying attention, I tend to use underscore
style or, for short names, just jam them together. I don't claim that's
better - it's just the habit from many years of C where those are the
conventions.
- I use a single tab instead of multiple spaces. The reason this is
better to listen to is that the screen reader just says "tab" for one
tab and "tab tab" for 2 tabs. If you're using 4 spaces, it has say
either "space space space space" or "4 spaces".
I'm sympathetic, but in my personal work I'm trying to move away from
tabs - and I would do that in my professional work too, if it wasn't for
the huge weight of legacy. (The source tree that I usually work with
has about 16 million lines of C in about 22K files.) Tabs cause too
many problems with inconsistent displays, where display programs add
annotations on the left without expanding tabs and mess up alignment.
Diff is the most obvious example, but I also have problems with programs
that add line numbers.
I'd say that the real answer is that the screen reader programs should
learn to do a bit more semantic interpretation, and talk about indenting
rather than about tabs and spaces. (And of course the display programs
should do the right thing with tabs, but that seems to be a losing battle.)
3. I put a comment after a close brace to say what it is closing. For
example, the brace to close a for loop I'll write "} // rof".
I don't, but I don't object. I would not use reversed words. How
would you pronounce "esle" or "elihw"? Also, since there may be
multiple levels of "for" or "if", you might want to include a summary of
the condition associated with the block.
- I put the opening brace for a code group on a separate line. That
way it lines up with the close brace (which I've commented).
That's a very uncommon style, and so it would feel unfamiliar. Do you
indent both, or just indent the contents?
The biggest problem, over the more usual brace-on-opening-line style, is
that it uses up a precious line of vertical space. Secondarily, it
seems like it breaks the connection between the compound-statement verb
(if, while, et cetera) and the block.
But mostly I'm happy with any brace / indentation style, as long as it's
consistent.
My preferred style is:
- Open and close brace, parenthesis, or bracket on the same line.
(This is rare for braces; the only cases that I can think of are
short C structure/array initializations and very short single-line
inline functions in JavaScript.) - If the block is going to span more than one line, the end of the
first line is one or more open markers, and the close markers are
indented to the same level as the open line. Usually this means
that the open is the end of the first line and the close is the
beginning of the last line, but I'll allow multiple opens on the
first line, matched by multiple closes on the last line. - Simple continuation of a non-nested argument list might just break
at the margin and continue indenting. - I never put the body of a compound statement on the first line.
- If the body of a compound statement is multiple lines, it gets
braces, whether or not it's one statement. - Or maybe: braces all the time.
My tastes and rules here are still evolving. OpenSCAD and JavaScript
have presented style questions that I haven't developed solid opinions on.
OpenSCAD makes very heavy use of what are arguably nested compound
statements - "translate(...) rotate(...) scale(...) something(...);" I
wouldn't want to always use braces and new lines, so that leaves me
uncertain when to break, when to indent, and when to use braces.
JavaScript makes very heavy use of nested statements - functions
inside objects inside objects inside lists, et cetera. I lean towards
fully following the rules above, breaking most bodies into multiple
lines with open and close on separate lines, but that can get a bit verbose.
How annoying is this stuff?
Not.
Annoying? Hardly! I’ve been writing code since the mid 60s. (I’m 72, started in middle school.) My style is similar though I am sighted. I do it for readability. Camel case is very readable and underscores are annoying to type. I also put a comment after a close brace. It’s an excellent habit for anyone. I don’t put the open brace on a new line, but I do put the close brace at the same indent level as the open.
I don’t use tabs instead of spaces because it editors seem to treat tabs inconsistently. Visually it doesn’t hurt. Interesting that the readers render it that way. I would have thought that a smart reader would indicate indent level, not characters.
My code tends to look like this:
difference() {
moduleCall();
// Remove
...
} // difference
I can’t say I am surprised that “readability” for a screen reader would be similar to that for a sighted person.
-Bob
Tucson AZ
On Aug 18, 2022, at 12:32, John Heim sconnie.johnnie@gmail.com wrote:
As a blind person, I have to listen to code. As such, I've developed habits that make it easier for me to do that. But I am wondering if other people are going to hate my style.
-
I always use what I think is called camel notation for identifiers. For example, thisIsaFunctionName. A screen reader is going to read that "this isa function name". If you write taht this_isa_function_name, it says "this underscore isa underscore function underscore name".
-
I use a single tab instead of multiple spaces. The reason this is better to listen to is that the screen reader just says "tab" for one tab and "tab tab" for 2 tabs. If you're using 4 spaces, it has say either "space space space space" or "4 spaces".
-
I put a comment after a close brace to say what it is closing. For example, the brace to close a for loop I'll write "} // rof".
-
I put the opening brace for a code group on a separate line. That way it lines up with the close brace (which I've commented).
How annoying is this stuff?
OpenSCAD mailing list
To unsubscribe send an email to discuss-leave@lists.openscad.org