Blind and Visually Impaired Community
↑
21
↓
Software engineers: how can I write my code to be more accessible for you? (self.Blind)
submitted by proboardslolv5
Note: I'm asking about making the code itself accessible, not the program that the code generates.
I once heard a story about someone who tried to change the code in their company's repository from tabs to spaces. Later that day, he was paid a visit by an engineer who is visually impaired and requires very large font sizes in order to read code. Since spaces render at a fixed width, this would make it impossible for him to read code which extends very far past the edge of the screen. Tabs can be configured to be the size of 1 space of indentation on his computer, making it easier for him to read code without having to scroll too far.
I've recently begun a project which I want to make open source. Part of being open source means making contributions to the repository accessible and inclusive, so I've decided to go with tabs following the previous engineer's example.
However, what other things can I implement in my repository's contribution and style guide in order to accommodate as many people as possible? Are there documentation generators which produce more accessible HTML than others? Is Doxygen good with screen readers? (This is a C library). Older C style guides require a max of 80 characters to fit on a single screen. Is this a good limit? Should it be smaller?
What are some things that would make code more accessible to visually impaired software engineers who want to contribute to the project?
I once heard a story about someone who tried to change the code in their company's repository from tabs to spaces. Later that day, he was paid a visit by an engineer who is visually impaired and requires very large font sizes in order to read code. Since spaces render at a fixed width, this would make it impossible for him to read code which extends very far past the edge of the screen. Tabs can be configured to be the size of 1 space of indentation on his computer, making it easier for him to read code without having to scroll too far.
I've recently begun a project which I want to make open source. Part of being open source means making contributions to the repository accessible and inclusive, so I've decided to go with tabs following the previous engineer's example.
However, what other things can I implement in my repository's contribution and style guide in order to accommodate as many people as possible? Are there documentation generators which produce more accessible HTML than others? Is Doxygen good with screen readers? (This is a C library). Older C style guides require a max of 80 characters to fit on a single screen. Is this a good limit? Should it be smaller?
What are some things that would make code more accessible to visually impaired software engineers who want to contribute to the project?
Marconius 7 points 2y ago
Use tabs instead of spaces. I can configure VoiceOver to read and count the indentation level of tabs, but it won't count the number of spaces unless I move the cursor character by character through the code which gets quite tiresome.
Make clear and concise comments, use understandable variable, parameter, and function/class/struct names, and I tend to keep consistent spacing between functions and chunks of code separated by blank lines. Oh, and please don't use emojis around your code, I find it super annoying when I run into that.
As for the repo, write proper markdown for your readme, using proper heading structure as if making an accessible website. Give all your links meaningful link text and don't use text like "click here."
Make clear and concise comments, use understandable variable, parameter, and function/class/struct names, and I tend to keep consistent spacing between functions and chunks of code separated by blank lines. Oh, and please don't use emojis around your code, I find it super annoying when I run into that.
As for the repo, write proper markdown for your readme, using proper heading structure as if making an accessible website. Give all your links meaningful link text and don't use text like "click here."
proboardslolv5 [OP] 6 points 2y ago
> Oh, and please don't use emojis around your code
Surely, the federal government keeps the names of such psychopaths on a list for monitoring, right?
Surely, the federal government keeps the names of such psychopaths on a list for monitoring, right?
Marconius 1 points 2y ago
I certainly hope they do. I'm going through the Codecademy SwiftUI course right now and the instructor absolutely loves using emojis everywhere in the training and it's super obnoxious.
proboardslolv5 [OP] 2 points 2y ago
How else will he connect with the totally radical young crowd of zoomers? Everyone knows that people under the age of 31 are illiterate and can only have their 30 second attention spans stimulated with emojis!
codeplaysleep 3 points 2y ago
You pretty much said everything I was going to. I will add that a slightly more verbose but easy to understand block of code is a lot more accessible than a magic one-liner. This isn't to say that everything should be so verbose and that you should never use a ternary operator or a one-line map/reduce - of course you should, we do that stuff all the time and when used appropriately it helps with code clarity. But it doesn't actually make things cleaner, if you have to be very clever, or use 800 parens to condense your code to a single line, it probably shouldn't be a single line.
But like everything else here, that and all of the things that make the code accessible are also just good coding practices in general.
But like everything else here, that and all of the things that make the code accessible are also just good coding practices in general.
[deleted] 4 points 2y ago
[deleted]
proboardslolv5 [OP] 2 points 2y ago
Lol, I think there's good arguments for both. Horizontal alignment is more consistent with spaces
[deleted] 2 points 2y ago
[deleted]
Marconius 1 points 2y ago
Immediately thought of this clip as soon as I read the ask about tabs vs. spaces from OP. Poor Richard, haha.
viciousSnowFlake 4 points 2y ago
Break your long one liners into multiple lines. That's the biggest "hassle" I've ran into so far.
proboardslolv5 [OP] 4 points 2y ago
Are you saying I should or should not do this?
Nighthawk321 2 points 2y ago
Not OP, but you should break them into multiple lines.
Fridux 1 points 2y ago
Since it's a C project you can enforce a coding style using the $1 tool, and don't have to worry about almost anything except for identifier names as everyone has access to the same tool and can format the code to whatever style they wish, reapplying the project's intended coding style on commit.
As for identifier names, I prefer them to be verbose and easy to pronounce by a speech synthesizer since I don't use Braille, have a slight preference for camel case, and don't like the Hungarian notation, though I usually default to whatever the standard library for the language uses, which in the case of C is terse snake case.
As for spaces versus tabs, I've never contributed to that debate, and now that I'm blind I have absolutely no reason to do it either since indentation is pretty much irrelevant to me.
---
Editing to add that Doxygen is perfectly fine for me; libevent and yajl use it for documentation and I didn't had trouble reading it with VoiceOver.
As for identifier names, I prefer them to be verbose and easy to pronounce by a speech synthesizer since I don't use Braille, have a slight preference for camel case, and don't like the Hungarian notation, though I usually default to whatever the standard library for the language uses, which in the case of C is terse snake case.
As for spaces versus tabs, I've never contributed to that debate, and now that I'm blind I have absolutely no reason to do it either since indentation is pretty much irrelevant to me.
---
Editing to add that Doxygen is perfectly fine for me; libevent and yajl use it for documentation and I didn't had trouble reading it with VoiceOver.
proboardslolv5 [OP] 1 points 2y ago
Do you know if indent works with MSVC? This project is going to primarily run on Windows. I know MSVC has its own idiosyncratic compiler hints that won't compile on GCC
Fridux 1 points 2y ago
That could be a problem, yes. Since you mentioned open source I assumed it would be something standards-compliant and cross-platform.
proboardslolv5 [OP] 1 points 2y ago
I'm going to try to be as standard-compliant as possible, but when exporting DLLs in MSVC you need certain compiler hints to indicate which functions are being exported and in which format (as well as macros to then import those functions when consuming the headers). There would be Linux, MacOS, POSIX, Android, etc. specific syntax for those platforms, but that would require the help of the community to contribute since I'm not personally interested in supporting those platforms, as I don't own any Apple products and have no intention to ever own any Apple products. I may or may not also include some Win32 calls depending on what I'm working with
Fridux 0 points 2y ago
That's only a problem because of your choice of tools, which will have other ramifications later on if anyone intends to port the code to other platforms. Both gcc and llvm are perfectly capable of producing DLLs on Windows.
zersiax 1 points 2y ago
Huh ...good one about the tabs vs spaces thing, I never really even thought about that and I'm a blind person :)
For people who use braille displays, the best limit you could reasonably expect to use , I would say, is 80 or 88 characters per line, this way they will fit on 80-cell braille displays. A lot of people will have 40-cell displays and they'd need to pan once to get the entire line, but 40 characters just isn't all that much where programming is concerned :)
I don't really know of documentation generators I prefer ...most of the ones I've seen spit out output that is at least readable :)
I honestly don't know of more things you could do to make code itself more accessible ... I'll give it some thought though. I will slap whoever decides to use emoji for variable names in any PR I get to review, though :P
For people who use braille displays, the best limit you could reasonably expect to use , I would say, is 80 or 88 characters per line, this way they will fit on 80-cell braille displays. A lot of people will have 40-cell displays and they'd need to pan once to get the entire line, but 40 characters just isn't all that much where programming is concerned :)
I don't really know of documentation generators I prefer ...most of the ones I've seen spit out output that is at least readable :)
I honestly don't know of more things you could do to make code itself more accessible ... I'll give it some thought though. I will slap whoever decides to use emoji for variable names in any PR I get to review, though :P
sacah2 1 points 2y ago
Interesting, side question if I may, I've always said don't limit line width, and let people choose how their editor handles it, or toggle line wrapping. Does this work with Braille displays, or should we hard limit lines to 80 characters?
zersiax 1 points 2y ago
Ehh ...I would not say its a hard requirement, more of a nice-to-have. Braille displays can pan the line, so if there's more text on the line than the display can show at once, you'd pan to the right to see the rest. Given there's various sizes of displays, it might still be required for some to pan even if your line is at 80 characters. I'd say leave it up to the developer.
proboardslolv5 [OP] 1 points 2y ago
Personally as a matter of style, I think that text wrapping is a poor way to structure code
proboardslolv5 [OP] 1 points 2y ago
Do you think some naming schemes are more accessible than others? Microsoft uses Hungarian notation to indicate the type of the variable in its name as well as whether or not it's a member of a class or struct. Would this context help or is it just redundant information?
zersiax 1 points 2y ago
I generally determine what a piece of code is by surrounding context, not so much naming scheme ...but then, it also depends on the language. Ruby has @ signs before instance variables, but I've never believed in prefixing members with M and such.
This nonprofit website is run by volunteers.
Please contribute if you can. Thank you!
Our mission is to provide everyone with access to large-
scale community websites for the good of humanity.
Without ads, without tracking, without greed.
scale community websites for the good of humanity.
Without ads, without tracking, without greed.
©2023 HumbleCat Inc • HumbleCat is a 501(c)3 nonprofit based in Michigan, USA.