Good Programming Practices: What to Do (or Not)

Introduction


Coding

Formatting Your Code
Why style matters

Universal Programmers Toolkit
Care and feeding of your code collection

Effective Proactive Debugging Techniques
It's all about the tools

Good Programming Practices
What to do (or not)

Banning Bad Bots
A short but effective script


Management

The Joy of Specs
How to (almost) guarantee a successful project

Habits of Successful Freelancers
Advice for success

How to Become a Great Programmer
One easy lesson!

Bidding on a Stranger's Project
The basics

Freelancing 101 - Don't Send That Email!
Pick up the phone instead

Ensuring Your Web Site Project Succeeds
Advice for clients


Photography

How to Take Great Photos (And Fix Lousy Ones), Part 1
Composing and shooting your photos

How to Take Great Photos (And Fix Lousy Ones), Part 2
Editing and postproduction

Good Programming Practices

Overview

Most programmers suck. No, I'm not trolling or being glib. I'm simply stating what I've concluded after updating countless other people's code over the years. In fact, statistically speaking, chances are your code sucks. Don't believe me? Here is a list of good programming habits that most people would agree are Good Things in principle, yet precious few adhere to in practice:

 

 

 

 

 

 

 

There's nothing worse than comments complaining about something unrelated to the code, especially when the code is poorly written to begin with. Make sure your house is clean before complaining about other people's houses.

 

If you want to go all the way and do the right thing, you'll actually document your code as well. That means writing a separate document (not comments in the code) that goes into more details on the operation and function of your code.

 

 

§         If the built-in functions change (e.g. you change languages or compilers) or if the third-party libraries change, you'll have to change only your wrapper functions, not your main application.

 

§         You can always add debugging code or breakpoints to your wrappers to trap when they're called. Don't think that's necessary? Try trapping all the calls to, say, the sqrt() function, counting how many times sqrt() is called during a typical run, or writing a message to a log every time sqrt() is called. You'll find those tasks to be far easier if you've replaced all calls to sqrt() with my_sqrt(). And before you go around making macros that simply replace sqrt() with my_sqrt(), remember that such things only serve to obfuscate code; it isn't always clear to the viewer that sqrt() really means my_sqrt(). If you want my_sqrt(), your should say my_sqrt().

 

 

 

 

connect_to_database(...) or die("Unable to connect to DB!");

 

This type of error handling is:

 

·        Lazy: you obviously copied and pasted it from a book or web site that explains how to connect to a database. You're a n00b.

·        Ungraceful: failure to connect to the database is not a sufficient reason to exit the entire application right then and there. Don't be low-class.

·        Inconsiderate: what if another module needs to do some clean-up before the application exits? Don't be selfish.

·        Unhelpful: of what real use is the message "Unable to connect to DB"? A better message might be "3-Sept-2006 12:34:33 pm: connect_to_database() failed on line "123" of module "foo" – at least if you're talking to a programmer. To the end user, even that "improved" message is mindless doublespeak. This says you're the type of old-school programmer geek they keep away from the customers. That is so 1980s.

 

 

 

 

 

 

 

§         Level 1 (high): accept user input

§         Level 2: taint check and normalize user input, and check for errors

§         Level 3: process user input according to business logic

§         Level 4 (low): store data

 

 

1.      Put a corresponding comment in the code

2.      Suggest an alternate method for generating more secure passwords (even if it's just a theory)

3.      Organize your code so that when the new password-generating scheme is put into place it will fit as seamlessly as possible with your existing code.

 

Conclusion

No programmer can ever implement all of these suggestions 100% of the time. Not only does one reach a point of diminishing returns, but also there will always be areas that are open to interpretation, opinion, and individual style.

 

But just because perfection isn't achievable doesn't mean you shouldn't strive for it. In fact, the most important thing you can do is to identify the area(s) listed above where your program is most lacking and take steps to fix it. For example, your program might have excellent database handling routines but your variable names may be completely unintuitive.

 

Half the battle is figuring out (and admitting) where your program needs improvement; the other half of the battle is doing something about it.

 



Return to Kim Moser's Generic Home Page.
Copyright © 2017 by Kim Moser (email)
Last modified: Wed 09 January 2008 17:29:53