Web Scripting and you

Oct 16, 2008

If there is one thing that I feel can be best learned from programming for the internet it’s modularity.  Programmers preach modularity through encapsulation and design models but ultimately sometimes it’s really easy to just throw in a hacky fix and be done with the whole mess.  Welcome to the “I need this fix last week” school of code updating.  Honestly, that kind of thing happens to the best of us.

Being that I am a web developer, specifically working in an interpreted language, there are two ways that things can go, clean, neat and easy to manage or a horribly mangled mess.  My first couple of full-scale projects on the web were more of the latter and less of the former.  I cobbled things together any way that worked within the time frame that I was given.  Ultimately this meant little to me at the time, but for the people that are maintaining the code now…  I am terribly sorry.  Fortunately, I know the poor sap that is currently updating the code so he has a resource to cut through the thick undergrowth of spaghetti.

Now fast forward a few projects and one ridiculously large CMS later and I have learned a few things about what not to do.  Lesson 1: don’t make a script that does everything.  Lesson 2: you are eventually going to have to look at that code again.  Lesson 3: When the code is not completely obvious (read this as print statements and built in functions being used in the simplest possible way) comments are always helpful. Lesson 4: even interpreted languages have debuggers, so use one. Lesson 5: make it modular.

Lessons 1-4 are things that everyone hears, ignores and then ultimately pays the price for.  Lesson 5 is something that is preached and never reached…  dig the rhyming scheme.  On the web, if you build something in a nice, chunked out way to begin with, your code will look like that forever more.  I promise.  Once you have built a handy little chunk like an order-processing script that just hums along and processes whatever you send it, you’ll never write a hack for this order or that one again.  I promise.  It won’t happen because you won’t need to.  You have a handy little piece of code that works like… say… an object!  WOW!  Who would have thunk it?

Now I write this not for the programmers that are in engineering teams out there working with a bunch of people that all have a standard that they follow and ultimately know all of this already.  I am writing this for the rogue programmer that has decided they are going to go it alone and do something stupid like write a custom CMS/Project Management System/Time tracker integrated tool… Man, that sounds really familiar.  Anyway, if you are going to tackle a large project all by your lonesome it is of the utmost importance that you make it as easy for yourself as possible.  I really like that I have built an ordering system where all I have to do is insert a new item and it is automagically updated and handled all over the place without any extra coding ever.  I don’t even have to do a database insert.  It’s all just done for me.  It’s really nice.

So some of the basic rules that I follow for no other reason than I have found them to work:

1) A script in a file does one thing.  Even if you think it should do x, y and z, it doesn’t.  If you coded it to do x, y and z all at the same time, one of those functions breaks on you, I have seen your code and your future, I know.  Trust me, one script, one purpose.

2) Create your directory structure BEFORE you write ANY code.  I generally include the following directories: page_elements, process, includes and templates.  This does not mean that you can’t expand, but generally 4 directories and root is the barest minimum.

3) If you think something should be an object, it probably should be.  Gee, I find myself pulling info from the database a row at a time an awful lot.  Should I make a row object?  Yes. You should.

4) One object, one file.  Don’t test me boy, see rule 1.

5) Break the system up into small, bite-sized pieces and create an API for plugins.  It can be rudimentary and even require a little code to plug the piece in, but you will save yourself a ton of work if you can just write the added feature without having to dig into anything else.

6) Figure out a layer structure and live by it.  I don’t care the model, just use it and make it work for you.  It doesn’t even have to be one of the widely recognized design patterns.  I use a home-grown MVC pattern myself and it works like a champ.

7) NO INLINE CSS! Yes, I have broken this rule from time to time, but eventually I go back and pull it out into a file

8) NO INLINE JAVSCRIPT! No, I haven’t broken this rule.  I understand that you have to put in even handlers where you want the script to fire, but your script should not live in the document.  Plus, who knows, you might want that toggle element display script somewhere other than in the single place you built it originally.

9) Break up your scripts and include them as needed.  Both CSS and Javascript should function properly where it is needed, but it should be excluded when not needed.  I know that some people write these monstrous CSS files with inline server-side scripts to add in the extra pieces when they are needed, but honestly, isn’t it easier on you and the server to just include files when they are needed and not load them at all when they are not?

10) Commenting!  You know that crazy function that you wrote which required bit-shifting to make it happen?  Remember how it took you three days to figure out how to do it?  It will take you 6 days to untangle what you did when you look at it again.  If you had to think about something before you wrote it, put in comments.  The person that ultimately follows after you will thank you, and that might just be YOU.

Very well, that is all.  Off with you.  Go about your programming and make the web a little better place.

Occam's Razor

Jan 10, 2008

I have a particular project that I work on every so often. It’s actually kind of a meta-project as I have to maintain a web-based project queue and management system, so it is a project for the sake of projects. Spiffy eh? Anyway, I haven’t had this thing break in a while which either means that I did such a nice, robust job of coding the darn thing that it is unbreakable (sure it is) or more likely, nobody has pushed this thing to the breaking point. Given enough time and enough monkeys. All of that aside, every so often, my boss comes up with new things that she would like the system to do, and I have to build them in. Fortunately, I built it in such a way that most everything just kind of “plugs in” not so much that I have an API and whatnot, but rather, I can simply build out a module and then just run an include and use it. Neat, isn’t it?

So, today I was told that she really wanted to be able to update team members on a project and then update the status of said users. Now, the way the thing works is you update the list of team members on a project and then edit the project again to set the status. This is a little cumbersome, we’ve discovered, simply because we don’t use the system the way we thought we would. Isn’t this always the case? So, my boss specifically, goes and toys with the team members as she is working on a project. This is dandy, except that she has to update the team and then go find the project again, right away. Not so good. What she asked for is a way to update the team and then immediately update the status of any given member of the new team list.

My first reaction, mentally, was ‘great, now I have to build out some crazy AJAX to go behind the scene, update the team list and then cobble together the list of the current team, push out some dynamic content to the page and then update things on the fly.’ This is not my idea of a good day. I could have spent all afternoon working on this. Now being the planner that I am, I sat back and thought about this. This promptly put me into a slight daze and I took about a 5-minute nap. When I woke up it dawned on me: the requirements I put together in my head were not what my boss asked for, they were what I interpreted. My solution still uses a little javascript, but now there are just 2 buttons. 1 says ‘save,’ the other says ‘save and exit.’ When you click save, everything you did gets saved and you are returned to the page. From there, the page automagically builds and includes all necessary pieces. If you click save and exit, everything you did will be saved and you will be pushed back to the main screen.

So, the takeaway from all of this is Occam’s razor applies very neatly to web projects. I love neat stuff that flies all over the screen and interacts with the server by making dynamic XHTML calls through activeX, but assuming all things are equal, the simplest answer is best. Why kill yourself and stress your server when you don’t need to?

Inflexible XML data structures

Jan 4, 2008

Happy new year! Going into the start of the new year, I have a project that has carried over from the moment I started my current job. I am working on the information architecture and interaction design of a web-based insurance tool. Something that I have run into recently is a document structure that was developed using XML containers. This, in and of itself, is not an issue. XML is a wonderful tool for dividing information up in a useful way. The problem lies in how the system is implemented. This, my friends, is where I ran into trouble with a particular detail in this project. Call it the proverbial bump in the road.

Generally speaking, when dealing with a database like one I use a lot, MySQL, you can run queries to retrieve data in any way you like. So long as the basic design is reasonably flexible, you can return anything you want. Apparently this isn’t so with the XML structure that was used on my current project. People would ask, ‘why is this a problem?’ On the outset it doesn’t seem like it would be. You figure out how you want to return the data and then you simply structure the XML containers appropriately. Great! Now along I come and I say, ‘this model stinks. The usability is nonexistent and we want to change the structure.’ Now what?

If the design were made to be flexible then it wouldn’t be a problem. The query would be changed and the structure would be re-vamped. On the fly no less. Nothing like some good-old on-demand technology. I am all about on-demand flexibility. Obviously if you are talking about running a report for some exceptionally large amount of data then flexibility will have to be considered along with efficiency, but hey! We’re talking about web experience here. People view things 10 at a time. We’re not talking about 300,000,000 documents. Closer to 300. With current server tech as it is, 300 documents, even with an extremely inefficient algorithm, would take almost no time to sort at all, then you produce the correct XML and ship everything off to the client. Done! Zip-bang!

Now, if you have an inflexible data structure going into the whole system, you can end up with some major issues if someone, like myself, comes along and says ‘this sucks. Fix it.’ Now what? You start over. That’s what. I made the mistake of coding a solution in a somewhat inflexible way and guess what? I had to re-work it. Some of the code was usable, but a lot of is was just lost time and lessons learned. Now the whole system is designed to be reasonably plug-able, though it’s still not a spiffy API, and as people request things, I write them, plug in the necessary code and roll on like the champion I feel like!

So, the take away from all of this, if you are looking at things from a front-end, client-side perspective, expect to run into this kind of thing. Programmers like to write code that does precisely what it is supposed to. Nothing more. So if you are going to suggest major overhaul kind of ideas, prepare yourself. You will meet some friction. If you are a coder and would like to avoid the nastiness associated with people asking you to start over, think about how you can make your life easier at the front end. Since I finished the plug-in system, my life has been much happier and the final timeline has been much shorter on all associated projects. Do your self a favor. Be flexible. Think flexible. Things change. Will you be ready?

Accessibility and graceful degradation

Dec 11, 2007

Something that I have learnt over time is how to make your site accessible for people that don’t have your perfect 20/20 vision, are working from a limited environment or just generally have old browsing capabilities. Believe it or not, people that visit my web sites still use old computers with old copies of Windows. Personally, I have made the Linux switch everywhere I can. That being said, I spend a certain amount of time surfing the web using Lynx. This is not due to the fact that I don’t have a GUI in Linux. I do. And I use firefox for my usual needs, but Lynx has a certain special place in my heart. It is in a class of browser that sees the web in much the same way that a screen reader does. For example, all of those really neat iframes that you use for dynamic content? Yeah, those come up as “iframe.” Totally unreadable. Totally unreachable. Iframe is an example of web technology that is web-inaccessible. Translate this as bad news.

Let’s talk about HTML and XHTML. These are both derivatives of SGML which is a generalized markup language that is used to describe data. That’s it. SGML doesn’t make things “look” a certain way. You won’t find it hanging around the local bar trying to pick up girls. It’s just data description. Kind of geeky, like that kid that sits in the back of class playing with his… calculator. So, then HTML was developed with it’s own DTDso that people could describe the information contained in their HTML documents.  Early HTML was easy to interpret if it was coded well, however most people are sloppy with their code.  This led the W3C to create a code validator.  Now, based on the DTD that you use your document may be standards complient or it may not.  Personally I really like to stay within the bounds of strict XHTML, though onMouseOver is deprecated, so Javascript kind of hoses the whole complience thing.

This leads us to the topic at hand: accessibility.  Considering that HTML and XHTML are used for simply describing data, why would a page be more or less accessible?  Well, let’s think about that kid that has MS, but still needs to get online research done for a class he’s taking, or better yet, consider Stephen Hawking.  Do you think that they would be particularly amused if they had to fill out a form and had to be pixel precise to click on the input field?  I promise you they wouldn’t.

Accessibility means that regardless of the browser or disability, your page should still be reasonably functional.  Now, this does not mean that your page should read minds, but there are some tags that should be very familiar. Learn and use the following:

<acronym> - The acronym tag describes what an acronym means.  Hover your mouse pointer over the first instance of HTML, XHTML, SGML and DTD.  The full name will pop up.  In some screen readers the full text will replace the acronym so that the human can interpret what the acronym means.

<label> - Label tags should be used with form inputs whenever possible.  This will ensure that your user will be able to click on either the form element or the associated text and the form element will gain focus.

<noscript> - Ok, if you have ever used Javascript, you are familiar with the <script> tag.  So, in contrast, the <noscript> tag surrounds what should happen if Javascript or other inline scripting language is disabled.

Aside from these few tags, you should also become familiar with the following attributes:

title - Title can be used on practically any element.  This should be used somewhat sparingly though, as using a title with an alt tag, for instance, could spell disaster for a screen reader which cannot interpret all of the attributes precisely as you might expect.

alt - EVERY IMAGE SHOULD HAVE AN ALT TAG!  No ifs ands or buts.  If the image is included in the page via the <img> tag, use an alt tag.  Furthermore, use descriptive alternate text.  img_21938740928374.jpg is not useful.   I will find out if you are doing this and I will stalk you in the night.  Alternate text doesn’t have to be perfect.  No two people are going to interpret it in precisely the same way, but if the image is of a bird in flight, use alternate text that says something like “bird in flight.”  People will understand enough to get by.

accesskey - The accesskey attribute sets the stage for people that are going to use the keyboard to navigate your site, or perhaps have a limited command set to work from.  This attribute enables people to use keyboard shortcuts to access form elements for their ease and convenience.  I recommend using this tag in your forms in general, though I strongly urge you to add accesskey to any form elements that a disabled user might be looking to use.

Moving forward, let’s discuss the <noscript> tag.  Whenever you have a Javascript effect on your site, consider whether there would be a problem if there were no Javascript enabled.  As a matter of fact, go to your site, turn off Javascript in the options and try navigating.  If your site topples like a house of cards, you need to re-work your Javascript.  I currently work for a company whose previous web-person didn’t account for people with no Javascript.  The corporate site is totally unnavigable without Javascript.  This is bad.  This is really bad.

Ensure that your scripts degrade gracefully.  If you have elements that are hidden from the user until the Javascript function is triggered, what happens if scripts are disabled?  I always run a special function at the end of the page that hides the elements I want hidden.  What this translates to is, if you have scripts disabled, the page displays everything.  The failsafe for my scripts is usability.

This brings us back to Lynx.  Don’t think that I had forgotten.  I browse my sites using Lynx.  I do this so that I can see what happens when nothing is viewable but text.  Lynx doesn’t even give any particular kind of formatting.  Pages are just a long string of words.  If you can open your site like this and still find everything easily you have successfully made your site accessible.  If your page looks like an amorphous mess then you have some work to do.

Now, go forth and make the web a more usable place.

Less is less, more is more. You do the math.

Dec 11, 2007

By this I don’t mean that you should fill every pixel on the screen with text, information and blinking, distracting graphics. What I really mean is that you should give yourself more time to accomplish what you are looking to do on the web. Sure, your reaction to this is going to be “duh, of course you should spend time thinking about what you are going to do online. All good jobs take time.” I say, oh young one, are you actually spending time where it needs to be spent? I suspect you aren’t.

First to the hard-core graphic designers in the crowd: Just because you spent extra time looking online through iStockPhoto finding that perfect picture does NOT mean that your design will encourage even one new customer. When it comes down to it, your average web user doesn’t care what your design looks like. It should fit the theme of the product being sold and the tone should be appropriate, but they really don’t care if you use one perfectly appropriate graphic or another. The nuance is generally totally lost. If you are going to consume days or even weeks coming up with that perfect design, it better slap my dad’s dentures right out of his head and make him spend 50% more than he otherwise would. If this isn’t the case, the ROI on those last few days or weeks that you spent is going to be painfully low. Think “solution” not “pretty.” Spend you time actually solving your customer’s problem.

Now on to the webmonkey/codemonkey. Do you really think that your customer cares if your algorithm is 2 nanoseconds faster on the server? They don’t. I promise you. If you are shaving tiny fractions of seconds off of a process for the sake of speeding the page load imperceptibly then you are really focusing on the wrong thing. Redirect. Think about what the customer is going to be looking for in the site that you are providing your code for. Does your search algorithm actually produce results? Can I be a bonehead and still get what I need from your code or do I have to specialize in what YOU went to school for in order to make the site work?

So then what should you be spending MORE time on? Well, the customer. The sale. Does the site work? If your AJAXy, cool looking thing that loads all kinds of server-side data brings their browser to its knees, you should strip it. I know, AJAX is the rage. I was guilty too. Why do you think that I am writing this? Seriously, though, AJAX is not the panacea, just like DHTML before it or blink and marquee before that. Spend time looking at how the page works and most importantly spend time looking at how to moderate your “cool factor.” Spend your time working on making a site that your customer will enjoy using. To the designer: spend time making the site easy to navigate. Put the information right at your customer’s fingertips. Make sure that they will never want to use a competitor’s site because yours sparkles so. Programmers: focus on making the site feature-rich in a way that your customer will appreciate. Make searches work properly. Listen to your IA, she knows what the search should do. Make sure that you match the search function match the customer needs. If you are going to use AJAX and other client-server interaction tools, make them lean and mean. Make them function well and MAKE SURE THEY DEGRADE WELL! There is nothing that will drive customers away faster than a site that doesn’t work for them.

Unless the site is ultimately useful, regardless of how cool the site is, the customer will walk away. The bottom line is stop doing your techno-masturbation and provide what the customer wants: a useful site. If you spend your time on this your customer will spend more money with your company or use the services or whatever your site is supposed to do. Furthermore, your boss may even thank you with a raise or a promotion. Less is less. More is more. Think about it. ; )