Programming guidelines: Best practices or basic professionalism?

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.