InfoWorld Home / Adventures in IT / Advice Line / Programming guidelines: Best practices or basic...
November 03, 2009

Programming guidelines: Best practices or basic professionalism?

Whether the subject is programming guidelines or nearly anything else, there's a difference between documenting and prescribing. Be clear on the task before you start

| Print | 6 comments|
238 Recommendations

Dear Bob ...

I have been recently asked to lead an effort to document existing programing guidelines as they exist in our group of about 25 developers. I know that in the macro sense you are against best practices, but I believe you are in favor of programming guidelines.

[ Keep up with app dev issues and trends with InfoWorld's Fatal Exception and Strategic Developer blogs. ]

Could you point me to some recommended reading?

- Standardizer

Dear Standardizer ...

For the record, I'm against the misbegotten notion that there is such a thing as a best practice. I'm hugely in favor of basic professionalism, and having formal programming guidelines is an example of the latter.

As to the specifics, it's been far too long since I've written code for a living (to give you an idea, object-oriented programming was just leaving the labs and becoming a business reality at the time), so I don't have any specific references to suggest, beyond this: If it has "Dummies" or "Complete Idiot" in the title, you might want to look for something more sophisticated.

I do have a suggestion, though: Get some clarity as to what you're supposed to be doing. If you're supposed to document existing guidelines, you don't need an outside reference. I'd think three or four one-hour sessions with five of the best would do the trick. Some thoughts to get you started:

  • The smaller the number of guidelines, the better. The table of contents should comfortably fit on one page, and each guideline should also fit on one page, with plenty of white space.
  • No showing off -- textbook answers need not apply. Each guideline should be completely and obviously practical.
  • Divide the guidelines into categories, and keep the team focused on one at a time. One category might be stylistic issues (indenting, naming conventions, and so forth). Another might be quality assurance. Program structure would be a third. Interfacing is almost certainly in there as well.
  • The last guideline should be when to remind everyone of the guidelines, which is just before every programming effort begins.

If, instead, your job is to develop recommended practices based on both internal knowledge and what outside experts recommend, you have a much bigger job in front of you. That isn't because what the outside experts recommend is so much more sophisticated and detailed.

It's because the gap between what people are doing and what they're supposed to do once the guidelines are in place will be bigger. Asking people to change how they work when they consider the way they do it now to be an expression of their expertise is a big challenge. Their egos will be involved, and rightly so.

All in all, if they're any good at what they do, you're probably better off having them hash out a consensus based on what each of them already thinks is the best way to do things. The result will be more than good enough, and they'll have a much easier time accepting it.

I'm sure there's more to say. I'm just not the one who can say it. So to all you developers out there reading this: Please use the Comments to weigh in with some good ideas.

Thanks!

- Bob

This story, "Programming guidelines: Best practices or basic professionalism?," was originally published at InfoWorld.com. Follow the latest developments in application development at InfoWorld.com.

Related Content...

White Paper

D2D Virtual Tape Library Replication Primer

This whitepaper explains the terminology and concepts behind Data Replication technologies and establishes some sizing rules through worked examples. Learn the new paradigm in disaster tolerance—protect data anywhere.

Download now »

White Paper

An Alternative to Virtualization for Datacenter Cost Savings

Server virtualization is a popular option for dealing with mounting datacenter costs. Another equally promising approach is the use of an Application Delivery Controller. Citrix NetScaler provides a low-cost way for organizations to reduce their server count and accrue cost savings from a reduction in space, cooling, power and personnel.

Download now »

White Paper

Why Your Firewall, VPN, and IEEE 802.11i Aren't Enough to Protect Your Network

The emergence of WLANs has created a new breed of security threats to enterprise networks.

Included in HP ProCurve WLAN solutions is security technology that alleviates threats from WLANs through:
* Monitoring wireless activity inside and out of the enterprise
* Classifying WLAN transmissions into harmful and harmless
* Preventing transmissions that pose a security threat to the enterprise network
* Locating participating devices for physical remediation

Download now »

White Paper

Bringing the Edge to the Data Center

Effectively address data protection challenges, implementing solutions that help store and protect business–critical data while cutting costs and improving efficiency and reliability.

Download now »
6 of 6 comments
Sign In or Register to comment
JamesMartin 3-Nov-09 3:25am
There is one thing that I always found frustrating with Visual Basic, and that was knowing who made a change, where, when and why. Don't know if the poster is using Visual Basic or not, but it is a common tool today. Sometimes the programmer is still there and you can ask him or her why something was done. A great time saver when troubleshooting problems, modifying code, and keeping from breaking something important.
ricke999 3-Nov-09 11:37am
That's what source control is for. Can you be considered a professional if you don't use it? Of course, that assumes that the developers actually enter a log message when they commit. Is that a best-practice or more basic professionalism?
Gray_Hair 3-Nov-09 12:54pm

It seems this conversation not advanced much in the last 30 years. Bobs advice is good. If "They" want documentation of "best practices", just give them a copy of MIL-STD-498 and go back to documenting the pragmatism and professionalism that keeps your organization running and call them "tailoring documents".

The "MIL-STD-498 Overview and Tailoring Guidebook" is about 98 pages and the "MIL-STD-498 Application and Reference Guidebook" is [only ;}] 516 pages. Both are available online as PDFs. If someone is overly attached to the document-it-then-build-it approach, (the old "waterfall" model) give them a copy of DOD-STD-2167A, and tell them, "You document it like this and we will build it."

Chuckle, my tongue is only partly in cheek. I spent a decade in the government business and all that stuff is no where near as onerous as it seems at first. Even the old 2167 (no A) had tailoring options for slimming down both process and documentation to fit the project.

Bottom line: Document what works, language by language, IDE by IDE, SDK by SDK, platform by platform, build tools first and if you use a tool twice document the way that worked best (I am a big fan of Open Source Content Management tools), back up early and back up often, and never, never even start without having configuration management totally bagged.

BigRonG 3-Nov-09 8:00pm
James Martin? There's a blast from the past. Basic principles will be all that could probably be agreed on. Most very good developers have a style that they strive to make consistent across their work. Like painters, they fall into classes but with individualistic characteristics. Trying to make different types of painters paint the same will be a study in madness. But if they are similar in style, you should be able to isolate a basic set of similarities to center your document on that they can all employ in their work.
brucebcox 4-Nov-09 11:17am
Are developers engineers or artists? Engineers have to follow code and standards, but still manage to satisfy their creative urges and produce works with a unique character. Why can't developers do that as well?
MikeM 5-Nov-09 10:05am
I work with three other developers. We had one guy no longer with us who wanted to create perl programming standards before we started. I told him no. where we are right now is that we've all read each other's code during providing user support and we've all written code. As we rewrite old modules and add new ones, our code gets better because we start seeing the actual benefits of standard indentations and organizing code into certain types of functional patterns. We've also been burned by using 'standardized' naming conventions. The only reason to have a standard is if you want to look something up. OTOH, if I don't know it's a standard (how many programmers are even going to look at the list?), then I won't look it up and will blithely go on my way. You're better off sponsoring some bull session on best coding practices and let the folks talk them out. That puts people on the same page thoughtwise and builds a team and when they come up with a new idea in two months, some lame-o anal retentive won't get to stop it because of published standards.

Sign up to receive InfoWorld Resource Alerts

Subscribe to the Lewis: Advice Line Newsletter

The one-stop resource center for IT professionals.

©1994-2009 Infoworld, Inc.