Good documentation doesn’t come easy
Documenting source code is rarely something a coder likes to do. I’m just as guilty as anyone else. I know it’s a “good thing”, but my natural inclination is to code first and document later. Sometimes later comes so late that it’s a chore to get it done. I’ve been forcing myself to document as I go, and it usually works out pretty well in the end.
I’m a control freak
What’s made this process easier for me is to completely dump the notion of auto-generated documentation (I’m looking at you, javadoc, jsdoc, yuidoc, ruby-doc and the like). Instead, I favor writing the documentation for a given piece of code with markdown.
I was feeling nostalgic over the holidays, and extolling the virtues of one of the first languages I enjoyed as a kid: LOGO. Then I dug back into the syntax of LOGO. Compared to modern programming languages, words like “terse” and “arcane” spring to mind.
Check out a couple code demos (view source):
The API attaches itself to a canvas tag, and supports chaining. I also decided to add some convenient methods for more traditional cartesian and polar coordinate systems.
More info can be found at the project page on GitHub. The open source project is in its early stages, but it’s already fun and potentially useful. Enjoy!
Ok, I’ve been keeping an eye on this, and with the recent preview 6, there are still some big missing pieces in their CSS3 support:
- CSS3 gradients
- Flexible box model
- Text shadow
if (document.body.style.msTransform !== 'undefined')
In short, it seems to have relative parity with Opera 10 as far as cool-yet-useful CSS3 features. Keep going, Microsoft, I’m totally cheering for you!
Continuing with my explorations in the webOS 1.4.5 SDK, I’ve picked out a couple of other useful calls to the PalmSystem object. Both can be added to the “hello world” example I started in part one, and they’re really quick.
A common requirement for mobile apps is the ability to respond to device orientation. I’m still digging around to see where you can hook into these events, but in the meantime here’s a simple call which is quite useful:
This tells webOS to let your app rotate along with the device orientation, switching from portrait to landscape as necessary. It’s a high-value one-liner call which should serve most orientation needs.
You can also specify a “locked” orientation with different strings in place of “free”. Options are: up (default portrait), down, left and right. So if you have a side-scroller game that would benefit from horizontal presentation, just use:
Step one: Make a web app and test it in Chrome or Safari.
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
Save this into a new folder (using a folder name of “hello” in this example) as index.html. This will become your app folder. You can test your app in Chrome or Safari by simply opening this file in your browser. Not terribly impressive, but hey, it’s a start.
I’m a big fan of Palm’s webOS. It’s based on open web standards, and Palm is doing everything I was expecting Apple to do with their iPhone when it was released (you may remember Steve Jobs saying “the web is the SDK”). Palm’s new OS is top notch, easy to develop for, and the developer relations folks are hard working and are very responsive.
It wasn’t a tough decision to go to their recent Developer Day conference, and right before I was about to shell out my $25 (seriously, only $25 for a conference, what a steal) I got a ping from Greg Vena, Dion Almaer and Ben Galbraith asking if I’d like to give a talk for the conference on Canvas, CSS and any other HTML5 graphics goodies I wanted to cover. Free registration? A chance to bend the ears of Palm’s engineering team while showing off some mobile webkit tricks? A free goodie bag which included an unlocked developer phone? Oh, hell yes.
If you missed the conference, Palm has a page up with videos from all the talks: