Site Redevelopment, part 2

More random notes as I continue to redevelop my personal web site, www.genghishack.com.

I’ve been organizing things in the background. I do a little bit more of this every day. Part of getting any large task done is just plugging away at it bit by bit, day by day, even if it shows no visible progress to the outside world.

One thing I needed to fix was the resume link – I wanted to put a new version of my resume up there, and I’m glad I did, because yesterday’s reshuffling of the files caused that link to break. Good thing I don’t have the URL for this site widely circulated yet.

I’ve had this hosting account for a few years, and it shows the signs of use. it’s an SSH account hosted on a linux server, which is good. SSH accounts are good. Don’t even get me started on how bad it is to have FTP-only access to a site that you’re trying to manage. People who think that’s good enough for a professional web developer simply don’t know what they’re doing. For one thing, it lets me run CVS. If you don’t know what CVS is, or if you’ve never used any form of revision control – if you aren’t even sure what the term means – stop now, waste no more time as a web developer, and hie thee off to the nearest bookstore to pick up a copy of Open Source Development with CVS. If you don’t want to spend the buckage, you can read it on the web. You want version control. Even if you’re working on projects all by yourself and not in conjunction with a group of other developers, you want to be able to go back to a previous version of your code when you’ve totally screwed things up, tag your code at various points, maintain separate branches of your code for separate projects, etc. Enough about CVS. Either you know it, or you don’t. CVS is one of those demarcation points in a developer’s career – Suffice to say I’m not much interested in working with anyone on a development project who hasn’t ever used some form of version control.

Back to subject. A clean workspace reflects a clean mind. The same goes for your desk as for your filesystem. If you’ve got stuff lying around everywhere in random locations, it’s going to be awfully hard to concentrate on what’s important. I don’t like to miss details. I like to know where all my information is. Organization is foundation-work for everything that comes after it. Another large part of getting any large task done is just putting everything where it goes.

My home directory is now organized into sites (I have several domains and subdomains pointing at this location), documents, logs, source files, my cvsroot, .ini files, the cgi-bin (required on this web server) and the temp directory. The sites folder contains the root directories for each of my web sites, whether presently operating, in progress, or defunct. The defunct ones I’ll need to clean up at some point, removing code that I want to re-use and deleting the rest, but for right now, they are where they belong. Easy to find and ready to be picked over when I have the time.

My personal site’s root directory needed to be cleaned up a lot, too. It contained artifacts of several old projects and lots of little one-off experiments that I stored there when I was not really paying much attention to how it looked (for a long time, this site was a one-page deal with nothing more than a title and a link to my resumé). The current directory structure of my site reflects much of my thinking about how to partition assets and tasks within the framework of a site. There’s an admin section, a world unto itself; a content directory, because presentation MUST be separated from processing; the always-present directories for css files, JavaScript, images and flash; an includes directory for stuff that must be included by all scripts; a directory to use when uploading files; a directory for libraries (classes, sets of functions and such) that may be loaded and used by some particular script; directories for each of the sections of the site, because I’d much rather have the url read http://mysite/directory/ than http://mysite/page.php; and the index and configuration files for the site. This makes sense to me. Again, I know where everything is. And since my idea of where things should go sometimes changes, I’ve written my code so that I can move a directory where I want it to go and change its location in the config file, and the entire site will know where to access that resource without a hiccup.

This foundational stuff may seem very basic, but it’s important to get the basics right. Once you’ve done that, you can take off from there and do all sorts of cool things. It’s like learning to read or write: the alphabet, the basic set of building blocks, is the hardest thing to learn and get right. It takes a while. You have to memorize all these weird shapes and sounds from nothing, and the order in which they go, and then how they relate to each other, and how to spell words from them, and then how to put the words into sentences – but once you’ve got those basics, you can take off from there into all sorts of worlds. It’s important to get that initial learning right. Get the foundations put solidly in place. If you don’t, you’ll have all kinds of problems later on trying to learn and use more advanced concepts.

So. This is what it is, trying to get all this foundational and framework stuff right. Putting all your tools in the right place. Making sure you have control. Anticipating what kinds of problems you’re going to face. Designing for them from the get-go.

Site Redevelopment

I’ve been doing this web thing since 1994 – you’d think I’d have gotten the hang of it by now. I’ve made a career out of it, having long since left the lucrative position of late-night radio DJ without looking back. They say that the cobbler’s son never has any shoes. Likewise, I have never, in my entire web career, had a decent web site of my own. I’m now working to redevelop my own web site using everything I’ve learned in the last 13 years about general design and development principles. These are some more-or-less random notes as I go along.

There are a few things I’ve learned. One is that no matter how much I work on the backend, coding and re-coding until I am satisfied that my code is the cleanest, most efficient, most reusable machine I can possibly build, no one else will care unless the site looks good and/or I have something to say. Oh well.

I’ve got a pretty decent-looking site right now: http://www.genghishack.com. But it’s boring. Yes, there’s a picture of me holding baby Hannah, but I might as well have an “under construction” gif (shudder) on the front page. I like the background colors, but what I’m really concerned with is how the backend framework is organized. This site is built on a set of files that I wrote intending to use as a template to stamp out other people’s sites – and have, several times. The code keeps evolving. It’s not terribly complex, but it’s an expression of clean design principles and proper separation of the various forms of functionality and presentation.

(One thing I’ve also learned is that I have ADD. Which means that I hardly ever finish anything in my personal life that I start. I’m working on that also. As you can see, I’m easily distracted by random thoughts. And bunnies.)

Back to the site. Right now, I’m working on the configuration file, where I set the constants and string variables that will be used throughout the entire site. This is my key to reusability and portability: make sure that there is only one place where you have to change your files’ path names. One. Everywhere in the code that you refer to a path or a URL to a file that is part of your site, begin the reference with the constant that refers to that location. Never, ever hard-code a path or URL. Don’t even use relative paths. Make the paths absolute and make them all begin with something like $PATH_FILES or some such. That way, you can move your directories around if you happen to find a different directory structure works better for you, or rename or replace your directories with ease.

I’m finding this holds true for path names, urls, and database table names. Data tables can and will change their names every time the code is re-used. They need to be abstracted, just like the user, pass, location, name and port of the database.

Which brings me to naming conventions. Another principle I incorporate into my code is that of clearly worded, understandable variable names. I find it best to put the function of the variable first and the name second, such as $TABLE_USER, $URL_IMAGES, $PATH_INCLUDES and so forth. I’m going to wind up with several of each type, and I like to be able to scan the code and see exactly what type I’m dealing with where. The capital letters for these types of variables are because I’m naming them as both constants and variables – for each one, I declare a constant (to be referred to as PATH_INCLUDES, for example) and then declare an equivalent string variable ($PATH_INCLUDES = PATH_INCLUDES). There are instances in which it’s appropriate and convenient to use one over the other. I like to have both available.

When I’m writing layouts, I use here-doc notation a lot. I tend to prefer this type of notation to templates, though that may change in the future. The point is that when I’m writing HTML, I use a lot of inline variables. The variable versions of the constants are very useful at times like these, because I don’t want to break out of my here-doc string to include a constant. I haven’t found a way to include those inside of a here-doc string, not even using {}. The constants are useful in other parts of the code. So, part of the function of the configuration file is to set them both.

I’m also learning to sanitize my user inputs. I never used to know anything about security vulnerabilities such as SQL injection attacks (which can cause you to lose large amounts of data, among other things), but am becoming wiser. Rather than the old database abstraction layers I used to use, which in themselves were a step, much earlier in my career, away from hard-coded MySQL or Oracle commands, I’ve switched entirely to using PEAR’s DB class and parameterizing all of my queries. It makes sense. Here is a cartoon that perfectly illustrates the dangers of SQL injection.