You are viewing a read-only archive of the Blogs.Harvard network. Learn more.

Web Accessibility Under the Law for Harvard

September 22, 2013 — JaZahn

What is required? Harvard is required to adhere to Section 508 of the Rehabilitation Act of 1973 (The most important Section of which is 504, but that doesn’t directly apply to web development).

The best way to understand the requirements of Section 508 is to read through the text of it. Specifically 1194.22 and by proxy, 1194.21. It should only take a few minutes. It’s not as bad to read through as the W3C’s Web Content Accessibility Guidelines (WCAG). And, more importantly it’s not as comprehensive.

Once you get the highlights, WebAIM has provided a handy checklist. WebAIM is an open consortium that exists just for discussions such as this, similar to what OWASP is for Security. From the spec, (a) through (j) are reasonably straightforward. (k) needs to be understood, as “text only versions” seems to be a common accessibility misconception and isn’t necessary if all of the other items are taken care of.

(l) is a biggie because it requires a different approach to javascript than 99% of js writers do. What it means is to make all interfaces possible to navigate without a mouse, in a way that’s readable to screen readers. That just means following the spirit of (a) through (j) as it pertains to your interface. This seems borderline impossible when you look at things you’ve built and try to add it in after the fact, but is much more reasonable when you design it from the start with this in mind.

Which seems to be a recurring theme when it comes to best practices. These things need to be thought about from the start, not thrown in last minute. So I think the solution for this is to spread information around. Not try to force this into existing projects, but bring them up as new projects / rewrites begin. It’s a lot to think about, I think the trick is to introduce the topics slowly but consistently into our culture until it becomes something we all know and just do without having to be told.

Posted in Uncategorized. Tags: , , , , , , . 3 Comments »

Documenting Documentation

August 28, 2013 — Michael D. Hilborn

I recently waded back into simple web application development (more on how that feels later), and one of the many aspects of coding that I’ve been refreshing myself on is how to best document what I’ve written so my future self doesn’t get too confused over what I implemented or why I implemented it in the way I did. The application is deadly simple, so simple that I hesitate to call it an application. The web page contacts a PHP script via an Ajax call, and the PHP script does its thing, sending back a JSON-encoded object. The client subsequently uses the object to display a message of success or failure.

As I said, deadly simple.

Nevertheless, as simple as the application is, I’ve been researching how best to document PHP and JavaScript. For PHP, the definitive answer appears to be phpDocumentor 2. For JavaScript, there is JSDoc. Here are some additional links that I found useful:

phpDocumentor

JSDOC

Note that I haven’t actually tried generating documentation with either toolset; that’s a completely different challenge. I’ve mostly been following the format so that my documentation can be printed/generated if somebody (aka me!) wishes. And what I’ve come to understand is that learning how to document a language feels almost as complicated as learning the language itself.

 

Posted in Development, Javascript, PHP, Uncategorized. Tags: , , , . Comments Off on Documenting Documentation »

Deciding on a Style Guide

December 15, 2012 — JaZahn

Recently a couple of groups here at work were brought together to try and standardize on a few things. The Software Development Community of Practice! Style guides came up. Everyone said they had no style guide and everyone agreed having a style guide would be worthwhile.

I had spent some time writing a style guide (customizing) so I was interested by this. I got to reflect on my style guide, how I’ve referred back to it in the year since I put it out there, and how I think it has helped or could help in this forum.

See the reason I created this style guide is not all that different from the reason these communities of practice are looking to create style guides. I was/am writing open source, and on the hope that someone will want to contribute to the project, I want a rule set defined so people won’t submit something unreadable.

For the community of practice, it’s a little different, but the spirit is the same. What they want is to have the option to point at something when a fellow developer is writing horrible code. The premise is you have a new developer and they don’t know how to write clean code.

The problem I have with this is everyone knows how to write clean code. And by everyone, I mean every professional software developer. If they’re not writing clean code, they’re not professional. Now that of course means if we are using student employees or taking in work from unknown outsiders (Open Source), that we are risking poorly written code being introduced and should therefore have a style guide. But if the premise is to have something for professional developers, I think it’s a waste of time.

Most style guides are 95% the same and we’re not talking about trying to enforce the 5% that is going to be different between individual developers. If ever a problem comes up with software developers where one is trying to say another’s code style is wrong, they should be able to say “google a style guide to see what best practices are” and be done with it.

Sadly, I’ve wasted more time arguing this than it would have taken to just agree, pick a guide that no one will ever use and move on.

Posted in Development, Open Source. Tags: , , . Comments Off on Deciding on a Style Guide »

Writing a Style Guide

May 12, 2012 — JaZahn

I took a look at the style guides of all of the most popular frameworks.

Yii Style Guide
Codeigniter Style Guide
Zend Style Guide
Symfony Style Guide
CakePHP Style Guide

Yii is the simplest. They just tell you what should go in the Model, Controller and View. I actually believe that’s the best thing when thinking of a framework as a framework, since a framework shouldn’t be telling you how to write your code, and you should never be mixing your code within the framework. A framework is a tool, but it should be on the primary developer to decide on the style that’s right for them and their team. However, I do understand that most of these style guides are talking about their framework as a project, which of course it is

There are a lot of topics to consider in a style guide. A lot of things popped up as I looked at the different style guides that I hadn’t even considered.

File Names
Class Names
Method Names
Method Definition
Class and File Names Using Common Words
Database Table Names
Constants
Variable Names
Member Visibility (Private / Protected)
Indentation
Commenting
Control Structures
The PHP Tag
Comparing Return Values and Typecasting
Logical Operators
Debugging Code
PHP Errors
Whitespace
Linebreaks
Compatibility
One File per Class
Bracket and Parenthetic Spacing
Localized Text
One Statement per Line
Strings (When to use Single or Double quotes)
SQL Queries
Default Function Arguments
Associative Arrays
Unit Tests

Some of the style guides got so long I kind of got angry. Trying to enforce things like whitespace, logical operators or indentation is foolish. It’s just too much and it takes away from the things that are actually important.

So what’s actually important?

What’s important is what people are going to read. Nobody wants to read through a 30 page style guide, and they won’t. The best solution I’ve found is to have 2 style guides. The first, important style guide is to outline the very essential rules you want for your project. Try to keep it short enough to fit on one page so someone may actually read the whole thing. Then, if you choose, you can have a nitty gritty style guide that outlines how you want your variables named and if you’re an indent nazi. You can always refer back to the nitty gritty if someone is submitting code that you find repugnant.

My style guide for Quizmo
My nitty-gritty style guide for Quizmo

Posted in ATG, PHP. Tags: , , , , , , , . Comments Off on Writing a Style Guide »
«
»