A Different Type of Article

Over the years I’ve seen many great tutorials on programming better in PHP. Many start with a number, then with a word like “techniques, practices, patterns, etc,” and end with a phrase like “for better PHP.” Examples like “8 Tips for Cleaner Code,” “5 Practices that make you’re life easier,” and the list goes on. I’ve enjoyed and learned a lot about making my PHP code better. However, there is a subject I’ve never really read or heard about before: characteristics of good PHP code.

What is the difference between characteristic and the other subjects above? To me tips, techniques, and practices are well-defined instructions that are straight forward. They may be advanced topics, but they are well-defined. In lots of ways I think of them as rules to follow.

A characteristic, for me at least, is a more abstract concept. Let me give you an example: readable. Several techniques and practices help towards having more readable. However, if a developers follows a few rules, it doesn’t necessary mean his code will be readable. Characteristics are traits that code have that exists, but aren’t easily defined into a set of rules.

Real Life Example

Lets look at a non-programming example. A person can have the characteristic of being “nice.” We all know nice people, and people who are not nice. A nice person might have a habit of saying hi to their co-workers in the morning. However, just because a person says hi to a co-worker in the morning doesn’t mean they are nice. It is impossible to quantify being “nice” into a set of rules and regulations. Being nice is a so much more than just following a few guidelines, hence it is a characteristic. Its the way a person acts in a large variety of situations.

If I am a person who isn’t nice, but I want to become nice, I can’t just google “10 tips on being nice,” follow them, and declare myself a “nice person.” I can’t just emulate things nice people do and expect the same results. Becoming a nice person requires hard work and serious reflection. I would need to take a step back and continuously analyze my actions over time.

Why Characteristics?

So why list characteristics? Writing great code is so much more than following guidelines. It is impossible to write a book of rules that will guarantee great work, yet so many people take this approach when programming. I’ve met several developers, that while reviewing their code, list rules and guidelines as to why they did everything they did. “I’ve commented every section of code.” “I’ve used the DAL for all the queries.” “I used X pattern for Y situation.” The list goes on, but the code they’ve produced looks, feels, and runs sub-par. The reason I like to focus on characteristics is that is helps me recognize there is more to programming than rules and guidelines. Best practices will only help you out so far. The ultimate test is after everything is said and done, and I review my work, is going through my list of characteristics and seeing if my code follows the list.

Like personal characteristics, programming code with great characteristics can take time and experience. Every year I learn more as I write more. I find weaknesses in my code. I make it a personal goal to improve the quality of my code, and I find it helpful to have a list of characteristics I strive for.

What Characteristics?

So what are desirable characteristics of good PHP code? Here is my own list, in no special order. This article is the first of a series which I will describe how to achieve these characteristics with the your code, and how to evaluate your code. So without further introduction, here is my personal list:

• Readable – Being able to easily read code is vital. Don’t ever assume you will be the only developer to ever read and maintain your code. I can’t think of a single project for the exception of my blog that I have been the only one who worked on it. Readable code has meaningful variables, good comments that help describe what’s going on. However, good variables and comments doesn’t necessarily mean your code is readable.
• Organized – While some people think this is the same as readable, organization is different and crucial to me. Readability is the ability to read your code, however organized code helps you find what your looking for. There are many techniques to help keep your code well organized, but the most important thing is at the end of the day, can your fellow developers find what they are looking for?
• Modular – I hear this word tossed around a lot when talking about programming. However, what really is modular? I like to define it as being able to take a part of your code and use it elsewhere with the least amount of headache.
• Relevant – While I hear a lot about Modular code, I don’t hear a lot about relevant code. While people might consider relevant in the modular or organized characteristic, I find it helps me to separate this out. Relevant to me means that code is where it belongs. Its easy to have code blur together and have purposes mixed. Relevant code means the grouping of code belongs together.
• Efficient – What good is code if it is slow, doesn’t scale, and will have to be re-written? Is being efficient is just following a handful of rules and guidelines?
• Practical – It may be efficient, it be organized, but is it practical? In the past I’ve written the “coolest” class, or so I thought, only to have a fellow developer tell him that my implementation is confusing, and overly complex. While many times we create code that isn’t robust enough, but it is possible to make stuff just complicated, over-designed, or just impractical. Keeping your code practical helps you and your team to make a good solution that is easy to maintain.
• Documented – Code that isn’t well documented will be a time drain. I know many developers who think keeping up documentation slows the development process down. However, without that documentation, the overall development process will suffer. Bringing new developers up to speed, maintenance, even just general development will be slowed down by “figuring stuff out.” Documentation is also more than just having a “wiki” or using comments.
• Longevous – The definition is to live a long life. There are two parts to having longevous code. First of all, when you’ve programmed or maintained some code, ask yourself. “How long will this last? Will this solution work well over time?” Then, the second part which I think is almost never asked: “when the time comes, how easily can I extend, or replace this code?” To often programmers “dig ruts” so-to-speak in projects. They code an aspect of a project that locks them into a situation that is extremely difficult to code out of.
• Secure – All of the time spent on development can be for nothing if it isn’t secure. Security in web development is a must. It doesn’t matter the size of the website, large or small, eventually someone will try to break it. Someone will try to compromise it. The consequences vary, from an annoyance, to destroying the entire business. Making your application secure is a skill all developers need.
• Safe – While some people think of this as the same as secure, for me safe PHP code means it handles errors correctly. Great PHP code handles errors correctly. If a PHP class fails, it should handle the error properly. It should also throw errors correctly when needed. If code is safe, I know that it will behave as it should, and properly let me know when it is not.

This article is the first of this series for me, and I’ll try to write an article for each characteristic. I will start on the top of the list and work my way down. Hopefully I can write one every week, and this can help PHP developers take a broader, overall look at their work. Principles, tips, and techniques are great, the are helpful, but without a broader view of things, developers can still develop sup-par code. Knowing the characteristics of good PHP code can help us strive to ensure we make great solutions. It allows us to sit back and really ask ourselves “does this code really have these characteristics?”

Related posts:

1. ASP .NET GridView Access to Data In Code
2. Zend Studio vs PHP Development Tools
3. Web Development 10-Years Ago & Now

Why, oh why, are website classes so extremely out of date in universities, colleges, and schools? I just spent the last few hours helping my wife with her Information Systems class. I’ve had to do similar assignments for technology classes, yet the things they are teaching are extremely out of date and a waste of time. Why? After taking these classes, to actually use HTML, I would have to unlearn 80% of what they taught, and re-learn from scratch.

It is one thing to keep things very simple. However, if I have a basic Account class, and I would expect to learn about Credits, Debits, and keeping a ledger. There isn’t a need to get into complex concepts or advanced journal entries. However, if I take an Accounting class, and they teach me incorrect concepts, that class would be 100% worthless. I’ve uploaded the project my wife had done for her class, after following their textbook and professors instructions. This is also after helping her remove as much “junk” HTML.

Her Website Assignment

For those HTML Gurus out there, if they look at the source, they’ll cringe. I haven’t seen this poor of HTML since the 90s. Also, guess what? The book they were following was published in 2008. How well does this example validate? Terrible. This was after I helped her strip every bad piece of HTML I could without “breaking” the instructions.

Why teach your students to use very, very old markup? I guess is the authors don’t have a clue. However, if I hired a person who says they know HTML, and the produced the stuff books teaches, I would very upset. I mean, who teaches their students to use background images like that? Here is what HTML classes need to teach:

HTML Structure

Don’t worry about styling at first. Just worry about the structure. That is why they invented CSS (Cascade Styles Sheets). Teach your students how to use your correct markup. Use strong, emphasis, and span tags. Here are some examples:

<!-- Bad -->
<img src="image.jpg">

<!-- Good -->
<img src="image.jpg" alt="My Dog" />

<-- Bad -->
<b>Bold</b>, <i>Italics</i>

<!-- Good -->
<strong>Bold</strong>, <em>Italics</em>

Once they have a good base for HTML structure, then you can move on to Styling. There is no need to use Font, B, or I tags.

Cascade Styling

I can see why a professor would be leery to teach about Cascade Style-sheets. They can be confusing, and a new concept for their students. Also, Information System classes usually only have 2-3 weeks before moving onto another subject. So keep is very, very basic. Don’t even touch on ID and CLASS attributes if you don’t have time. Just show changing the colors of links, and maybe making strong and emphasis tags different colors. Keep it simple. However, do NOT resort to deprecated methods that may seem easier to use at first, but hurt the student’s full education on the subject.

Teach Principles, Not Motions

My wife’s professor held an optional saturday class to help with the assignment. If a student went, the teacher would walk through, step-by-step, what to put into notepad to make their websites. However, there wasn’t any discuss as to why they were typing what they we’re. Unfortunately, I feel like they were probably just going through the motions. The goal of teaching students is that they walk away with something. If you’re just spoon feeding the students what to type, what good is it doing? Isn’t it just a waste of time?

Don’t spend time getting a better “end result” by sacrificing the learning process. Teach students the “why” for what they are doing. If that means you only mention CSS, show how it works, but not require the students to write any, so be it. I know technology can be extremely difficult to teach. Many students have a hard time grasping concepts. Technology professions, such as website designers, usually rely heavily on self-taught technologies. Traditional classes usually aren’t well adapt to keeping up with the content.

What Should Professors Do?

Don’t worry about crazy backgrounds, changing colors, and different font sizes. Focus on good, validated content. If its super simple, thats fine. You can tell your students if they are interested in learning more, point them to websites like W3Schools.

Also, I would say a large portion of the blame lies on the Book Publishers. I would assume many of these teachers and professors are teaching general information systems classes. They aren’t experienced web designers and just teach what is in the books. The fact that students are buying brand new books with outdated content is rediculous. Maybe 2-3 years out of date, but not a decade.

I don’t know what else, other then there is nothing that drives me crazy more than sitting in a class learning something the wrong way.

Related posts:

1. CSS – ID vs Class
2. PHP 6 Books – Did I Miss Something?
3. iPhone SDK – Learning the Basics by Removing the Touch

The big issue is that people who just write Cascading Style Sheets usually won’t run into problems if they are more lax with their use of IDs. Its the people after who coming in trying to add advanced JavaScript features that will end up becoming very, very frustrated.

Why does it matter? Because an ID and Class have one major difference:

ID is supose to be 100% unique to a single HTML element through the entire HTML document. Class can be shared among many elements.

Example:

<!-- This HTML element is using an ID -->
<p id="text">This is using an ID</p>

<!-- This HTML element is uing a class -->
<p class="text">This is using a class</p>

What is the big deal? For CSS designers, not a whole lot. In fact, IDs have a higher specificity, so some CSS designers default to using an ID just because it is more convenient. The problem is when your boss say “hey, we need two paragraphs.” The developer copies a new paragraph in and to keep the formatting, adds another ID tag. Now we’ve broke the rule about only having one ID in an HTML document. Sure, it renders fine, but if a JavaScript developer tries to add additional features, they will have to code around these problems.

So when should you use ID and when do you use a class? Here is my rule of thumb:

Unless you are 100% sure that you will never, ever have a duplicate element name on the same page, use a class. When in doubt, use a class. Only use an ID when you’re positive it will always be unique.

Examples of when I would use an ID are:

• Unique parts of page layout: <div id=”header”></div><div id=”content”></div><div id=”footer”></div>
• Identifying specific items: <div id=”post-32″></div><div id=”item-123″></div>

If it doesn’t fall into those two categories, I usually won’t use an ID. Most of the time, I’ve never had moment where I wished a developer had used a ID instead of a class. But I’ve had many times where I wish an element used classes intead of ID.

Related posts:

1. ASP .NET Accessing Session, Request, Response, etc from within a Class
2. ASP .NET 2.0, GridViews, HyperLinkField, and JavaScript
3. iPhone Web Development: Controlling the viewport via Javascript