Cory Bohon

I’ve been programming for several years now and every time I start to write a line of code, I think about the documentation that I’ll need to write for either people who could read my code later (comments in code) or the users of my program (user documentation). I’ve seen several programmers both in academia and full-time developers that don’t comment their code. I firmly believe in commenting code for several reasons, but I just wanted to point out a couple reasons as well as some methods that I use in my own code commenting.

Reasons
Commenting for the future
If you don’t comment your code for any other reason, please, please, please, do it for this reason. If you’re part of a large project where you’re constantly updating your code, then this might not be as big of a problem, but if you rarely update your code, you definitely need a record of what things do.

Making sure you comment what things do, what needs to be updated (or fixed), etc. makes life a whole lot easier when you come back to your code down the road. Chances are you’ll be writing so much code that you won’t remember exactly what certain functions do or what a line of code might do.

Another reason to always document code is that you might not be the one working on the same code down the road. Especially if you’re involved in a large project or with a large company. And let’s hope it’s because you were promoted (and not fired for not documenting code ).

Comment the head of documents
I always comment the head of every document in my program (program files, header files, etc.). I use it as a record of the filename, who initially programmed that particular document, the date of initial programming, and a description of what that file does.

In addition to adding the regular doldrum of information at the head of the document, you could also add licensing information such as copyrights, EULA, etc.

Add a log file at the head of the document
Adding a log file at the beginning of your program files can generally be a good place to store information such as a revision log or changes you’d like to make down the road.

Comment Functions and Class Methods
When you comment functions and class methods you’re making a record of what that particular piece of code does. As mentioned by some of the reasons above, this is a good idea if you’re going to be coming back to your code down the road. Plus, if you have multiple people working on a project, this lets others instantly see what your function or method is doing. Look below to see how I comment functions and methods.

Commenting Methods

Commenting the head of a document

Below is an example of how I document all of the headings of my program files.

/*
Filename: MyProgram.java
Author: Cory Bohon
Date: Mar-23-2010
Description: This is the most awesome program you'll find anywhere. Srsly.

Version Log:
1.0.1 - Fixed bugs, added awesomeness
1.0 - Initial release to awesomize the world
0.1 - Beta version of awesomeness -- ADD MORE AWESOMENESS
*/

Commenting Functions and Methods

I like to use the Javadoc method of commenting functions and class methods. I even use it for some C++ code that I do, just simply because I think it’s a really efficient way to document functions and methods. Below is an example of this commenting method.

/**
* Returns the my_name variable
* @param none
* @return a string type with the name of the user
*/
string MyProgram::get_name(void)
{
return my_name;
}

I hope this post has helped some people see why it’s important to document your code. If you’re already documenting your code properly, I hope that you have learned some tips from the ways I’m documenting my code. And if you have any tips for me or some tips that I have missed, please leave a comment, or send me a message on Twitter.

If you’re following my Twitter feed, you probably know that I’ve been ecstatic about a fairly new content management system for Digital Humanists creating digital archives. The web software is called Omeka, and it’s out of the Center for Digital Humanities at George Mason University in Virginia.

Omeka has a rich API (application programming interface) that lets developers and creatives alike create awesome plugins and additional content that flows right along side of the CMS. I have been actively developing Omeka plugins for the past academic year at my university in hopes of making Omeka more accessible to visually impaired people accessing the Omeka archives. The development was sponsored by two grant-related projects that I’m involved with. The first project is LookListenTouch.org which I worked for Fall 2009, and BrailleSC.org that I’m currently working on.

People who are visually impaired generally access websites using screen reading software like JAWS or Apple’s screen reader VoiceOver. This software reads aloud what’s on the screen, but screen readers don’t work well with certain web content, namely Adobe Flash, JavaScript and Java applets. Fortunately, Omeka’s front-end doesn’t rely on any of the technologies, making it pretty accessible out-of-the-box. However, the accessibility plugins I’ve developed expand on the universal design model, making Omeka even more accessible.

The first of the plugins is an Access Keys plugin. This plugin lets the administrator assign Access Keys, which are one-character keyboard shortcuts, to basic Omeka functionality, such as go to the home page, browse by items, browse by collections, skip to next item, skip to previous item, and skip directly to the content. Normally people accessing websites with a screen reader need to listen to a list of menu items each and every time they listen to a page being read, but with the Access Keys model, they can memorize a set of keys, then jump to any page they wish to go to. For example, if you wanted to go to the search page, you can press Control + S and go directly to the search page in Omeka.

Access Keys can provide a ton of usability for user accessing a particular website, making navigation easier than ever before. The thing is, Access Keys have been around since around 1999 — why haven’t they been used before? Well, I’d suggest that’s partially because different web browsers use different modifier keys (i.e. pressing control, command, or shift before pressing the access key in order to activate a link). That’s why BrailleSC.org and LookListenTouch.org is advocating the standardization of modifier keys across different browsers, operating systems, and versions of browsers. This would make life easier for users and developers alike.

Continuing on the idea of Access Keys, I’ve also developed a custom Access Keys plugin that will allow an Omeka administrator to specify up-to 10 URLs and Access Keys that will be available from any page inside of Omeka. For example, you could go to Google.com by pressing Control + G.

Of course, Access Keys are limited to the number of letters and numbers available on the keyboard, so that’s 26 + 10 = 36 available keys. Symbols are not available for assigning Access Keys, and remember that if the shortcut assigned is also a shortcut for the web browser (i.e. in Internet Explorer Control + B is for bookmarking pages), then the assignment will overwrite the browser functionality.

The Last plugin that I’ve completed is one called “TextZoom” that, like its name implies, lets the user enlarge the text on the page. When the admin enables this plugin, they also can specify Access Keys for the enlargement functions. There is five levels of enlargement: default, small, medium, large, and extra large. When a user selects any of the enlargement levels, the settings are automatically remembered for 30-days using a cookie, so when they visit the site again, the text will automatically be enlarged for them. The user can then press the default option to go back to the default site and remove the cookie from their browser.

There are other plugins that I’m working on, including a Google Analytics plugin that will let an administrator look at current website tracking information right from within the admin pages.

Where Can You Get The Plugins?
I have the three plugins mention in detail above available for download at BrailleSC.org/development. I also have the source listed on my own development wiki at CoryBohon.com/development. The plugins are completely open source, so if you wish to take the source code an improve it you can under the terms of the included GNU public license.

If you have any questions about the plugins, you can email me directly at cory [at] corybohon [dot] com or cory [at] braillesc [dot] org.

As many of you may know, I’ve been doing some programming on the side (and part of my course work at my university). From programming in Java to PHP, I’ve written a good number of applications over the past few years, and I’ve decided to open all of those apps up.

If you go to my Development Wiki, you’ll find a list of the programming languages that I currently have source code listed for. When you click on those, you’ll be able to see individual projects that you can then look at the source code for, and in some instances, download the source code in a nice .zip format.

Most of this code has been sitting around on my MacBook Pro for the last year or so without being useful, so I figured that I would put it to good use. If you’re a C.S. student, or just someone looking to learn more about programming, check out the Development Wiki. I also have plans for a Java programming screencast/blog that will allow others to learn how to program in an easy way.

If you are at all interested in the Java programming tutorials, feel free to leave a comment and let me know your level of computer experience and if you’ve programmed before. I would really like to see more people learning how to program as technology is and will be a key involvement in the future.

Last week I told you about my iPhone site that I create using Dashcode. These sites are extremely easy to create using Apple’s widget creation software that comes packaged with the Xcode download. In this post, I’m going to walk you through turning any RSS feed into an iPhone site that is updated automatically when new entries are created.

This things first, you’ll need an RSS feed from a blog, Twitter feed, etc. When you have Dashcode installed, you can launch it by going to /Developer/Applications. This is where Xcode, IB, and Dashcode are stored. When you first launch the application you will be presented with a pop-up that asks you wish type of template you would like to create. For this tutorial we’ll be using the Web Application > RSS template.

When you click Choose, your template will be built. As of now you have a fully functional iPhone web application; however, you need to input your RSS feed for it to actually work. Under the Application Attributes section you will be able to add your RSS feed in the Feed URL section. Be sure to type the feed in exactly as it is (for example, my blog feed is http://corybohon.com/feed/). From this section you can also edit the number of articles that are displayed, and the date ranges.

You now have a completely useable web app. To test it, click the “Run” button in the top-left corner of the screen. Dashcode will then launch the iPhone simulator and show you what the web app looks like in mobile Safari. Now let’s export is and move it to a internet-accessible server.

Back in Dashcode, click the Share button. Under the account, select localhost. This will export the web app as a folder ready for you to upload to your web server. Click the “Save to Disk…” button and a folder will be created in the location you specify. If you have a MobileMe account, you can easily add it and upload it straight from Dashcode by clicking on the new account option from the drop-down box.