These are the most common and most annoying mistakes I see in web development code on a daily basis. Well, Ok, it’s the things that annoyed me most TODAY, but it’s not unique. It’s mostly PHP and MySQL stuff here, but the same abuses take place anywhere the language allows it.
1. Database prefixes. I find so many database tables that use a “table” or a “tbl” prefix. Are you serious? Do you think we don’t already know it’s a table we’re looking at? Likewise, some developers find it somehow necessary to use “column” or “col” in their column names. I mean really… do you pin your own name upside down on your shirt? Seriously, this type of labeling is completely unnecessary and it probably reveals you as the half-baked amateur that you are. Label your column names descriptively: too little info is bad, but too much is no better.
The one exception I make to this rule is this: be verbose with your primary keys because you’ll use those in all of your join statements. I know it’s easier to code if every table uses the ubiquitous “id” as the primary key, but if you ever have to do complex MySQL joins for reporting queries you’ll appreciate the fact that user_id or post_id references the same thing no matter which table it’s used in.
2. Function name prefixes. If you come across a project that uses functions declared in the main namespace it’s not much consolation that the function names are all grouped by a unique prefix. It’s like that Seinfeld bit about Chicken McNuggets: “If it McComes form where I McThink it does, I don’t want to McEat it!” Prefixed functions are the pink slime of development… they might sustain you and your project, but there’s gotta be something better on the menu.
PHP’s function_exists() function goes right along with this… if you are using this to wrap your function definitions, then ask yourself why aren’t you using a class? But if you’re asking this, you’re probably “developing” in WordPress, so you may not know what a class is. Sigh.
3. No Documentation. I’m convinced any college Freshman English Lit major could hire a developer with a pretty good fill rate — all they would have to do is read the comments. If a function does not include a description and a detail of its inputs and outputs, chances are the developer is lazy, incompetent, or both. I can understand not being able to write good code, but omitting docs? All you have to do is say your input expects a string or an array or something or just tell us what the function does, and do not ever just repeat the function name to fulfill the requirement: you missed the point.
Compare this doozy, worthy of a spanking:
<?php // Get user types
function get_user_types($id) {
//... code here...
}
To this:
<?php /**
* Gets a list of active children user-types for the given $job_id. Called by
* the /contacts/referrals page.
*
* @param integer $job_id defining the parent Job from the "jobs" table.
* @return array of key/value pairs indicating user-type and their priority level
*/
function get_user_types($job_id) {
//... code here...
}
Can you see the difference? I don't even need to read your code: one look at your documentation and I can tell who I would want to hire. Point is this: if you are unleashing your code spawn on the populace, it's your responsibility to document it. Do not force others to wade through your code, no matter how awesome you think it is.
4. Logic in your HTML. Yes, this one is a doozy, and it's soooo common (obligatory stinkeye to WordPress here). Loops, If-statements, and other conditionals really don't belong in your HTML. They belong in a separate layer of your application. Yes, it can be very useful to have some control over your view for readability reasons, but it's so often abused that I must mention it here as a noobie-no-no. Morphine is a great drug -- it's also often abused. Don't overdo it. If you really need to tweak output or formatting in your view layer and that's the only place to do it, well, ok. But if the calculations can be done more efficiently upstream and leave you with a cleaner HTML view that doesn't force designers to learn programming skills, then why not go for the win-win and do it that way?
5. Inconsistent or mixed return values. Your function shouldn't need an interpreter for someone to use it. If it's validating input, then try returning a simple boolean true/false. Don't return a string "success" if it worked and an error message if it didn't -- that's not intuitive for anyone who's worked with regular logic-flow structures. If your function sometimes returns an array or maybe sometimes a string and oh yes, sometimes a boolean, chances are you wrote it wrong. Keep it simple. Convenience can be handy, but don't go overboard trying to handle all kinds of input. In PHP especially, don't rely on literal true/false values since PHP's data types are a bit dubious.
There's so much bad code out there. If you know an experienced developer, ask him/her to review your code. Paired programming is a great way to learn. Don't assume that what you're writing is the best or only way, and be prepared to erase lots of stuff. Iterations can breed progress.
-- Everett Griffiths