Skip to main content
Welcome guest. | Register | Login | Post

Thoughts on Web Programming Style

1 reply [Last post]
supermike's picture
Joined: 2006-02-17

After spending 4 moonlight years (occasional nights and weekends) on a project, I've come to some conclusions:

* Build the app as rapidly as possible, anyway you can see fit. Get the 0.5 prototype working great. But get ready to forget about using that code as is. Some may feel contrary to this, but here's the thing. If you've spent 4 years on an app, it's like a Shangri-La. After awhile, you're afraid to touch it for fear your new change will bring the house of cards down. You'll also be blinded into thinking things are too good to change and your bias will keep you from doing things the proper way.

* Using this somewhat finished prototype, now write the functional specification from all the features of the prototype. You'll probably have to look at the sourcecode a little too as you do this. You'll think you've got it all documented but more than likely you'll have to improve the functional specification as you go. If you're not familiar with a functional specification, it's an outline (I. II. III., A. B. C., 1. 2. 3., a. b. c.) of major and minor functions of the app. You describe what functions it has and how a user interacts with it. You describe the GUI and the workflow for most normal use cases. You write down the rules of the game, so to say.

* Write down the ground rules for the programming style of the app. Some tips:

- Set a variable naming convention and stick with it.

- Make almost everything CSS-addressable.

- Pages with the least graphics, or have reusable graphics from page to page, load much faster than otherwise.

- If you can simulate a graphic element in CSS, the page is cleaner and loads much faster.

- IMG tags are bad because you have to hunt them down to change things out if you want to reskin an app. Instead, stick the image loading in CSS instead with the background and url() technique so that this way your app is "skinnable".

- You don't have to put a rounded corner on every cotton-picking thing in order to make your app cooler than the next guy's. You'll find the page is a little slower if you do. Instead, dress it up with CSS rather than loading little PNG files in the corners of things to make it look like rounded corners.

- You'll find that you can dress up an app "just enough" simply by giving it a slick-looking banner, colorizing some buttons, using a color scheme that makes sense, and using a background image on fields with CSS.

- After awhile you begin to recognize a pattern in your web pages where you do the same sorts of things in a certain order. Great. Build a template from that, such as FILE-INCLUDE SECTION, READ COOKIES SECTION, READ SETTINGS FILE SECTION, READ QUERY PARAMS SECTION, etc. Then, reuse that from page to page to make readable code. Not every page will use a section, but you should paste the section comment, anyway, so that other eyes can understand what's going on.

- Utilize a master settings file.

- Place the database SQL in the master settings file, never in the code.

- Utilize a class file that abstracts all db calls. Never make native API db calls in your app. That way, you can change one single class file and point the whole app to a different kind of database.

- Quit interspersing HTML and page source code logic, as in:

// your code here
<? if ($bFoo) { ?>
<? } ?>

...It may start out to be nothing at first, but after a few years of editing the same pages, you'll find this grows into a monster and the code is almost completely unreadable -- especially if you are forced into nested layers of complex conditional logic. Instead, get rid of an HTML section on your page altogether. Instead, draw the GUI by making a class of gadgets that have HTML/XHTML properties you can set on them and then draw them. Connect the gadgets like Lego's. Ensure that each gadget is fully addressable with CSS to change most of their look-and-feel, making the whole app skinnable. If you do this right, then your page class file will be the only one that has the echo HTML statements in it, while all your other pages simply call the gadget methods from this page class file to achieve the desired effects.

* Now, rebuild the app, page by page. Remember, again, draw the page GUI using gadget objects with properties that you connect like Lego's. By doing it this way, you make your app better, faster, and less time-consuming for upgrades, bug fixes, teamwork, readability/comprehension, etc. You can also leverage this code again and again on other projects, building your own homegrown framework that you understand (because you built it).

* You'll also find that orphaned code tends to go away or be easier to eliminate if you rebuild the app again from scratch, using the functional specification.

* Put this version out as the 0.5 version for others to improve upon.

free-zombie's picture
Joined: 2006-03-08

I am currently playing around with mod_python and next to no HTML in code. I have written a Template class that can be nested and that I use consistently through the site.
I know that working without seperating of form and function, things can become difficult, and with intertwined php and html things become really ugly. With clean seperation the way I do it, I need to write a template for nearly everything, but the code becomes bliss: (example: displaying a blog post from dict `p')