Examples of developer guidelines to bring a new developer up to speed

Question

Here are some good examples of coding guidelines:

• What should coding guidelines do, and are there any good examples of guidelines?

What about more general guidelines? Like the VCS process, communications, etc. I want to write something like this, and it would be nice to get some ideas from what others have come up with after many trials and errors ;-)

I'm not talking about manuals with dozens or hundreds of pages detailing every little process. More like a poster for reference.

Thanks!

Answer 1

The specific guidelines you choose to provide and document really depend on the nature of your group, the kinds of organizational problems you have (or foresee), and the culture you want to foster.

But here are (from my experience) some guidelines on producing guidelines:

1. Keep them short and simple. No one reads (or remembers) dozens of pages of rules and guidelines. It's both a waste of time to create and causes frustration in your development community.
2. Don't be a control freak. Unless you're building a nuclear reactor or space ship, the value of super stringent guidelines that everyone must understand and adhere to has diminishing returns.
3. Focus on fundamentals. Make sure that your guidelines cover those things that developers deals with every day (eg. version control). Leave the esoteric issues to the side - at least initially.
4. Help people finds things. Guidelines that help people locate existing resources, tools, are far more helpful than those that tell people what to do.
5. Encourage team members to contribute. Guidelines that people feel they own and contributed to (grassroots) are more likely to be followed than 'edicts' from on high.

Answer 2

In my personal opinion, documenting every bit of how your processes work and then sitting new developers down with the "guideline binder" is a surefire way to get developers to forget or ignore all your guidelines.

The most effective approach I've used is to have the new developer shadow either the team lead or another more senior developer for a day, where the lead can describe what he's doing and how to do common tasks, and then follow that up with the lead shadowing the new hire, not writing anything but devoting 100% of their time to watching them go through the process.

Yes, it's more of a time sink for a senior developer than plopping someone down with a big old binder, but chances are the binder will be out of date, or the sheer volume of information with no practice or practical experience will result in guidelines being ignored.

Answer 3

I find it more effective to have a few code reviews - especially for newcomers. If they need guidelines there are good ones (and bad ones) all over the internets.

As for the other parts of the process, I have written a few in the past.

I create a document explaining what tools are used, where to get them, how to get accounts, what the URLs are for svn repos, bug tracking, build server, etc.

Basically document all the things you do to write code, check in code, do builds, report fix bugs, ship the product, etc.

Answer 4

Your team should embrace the guidelines as their own, something which makes their life easier, and not see them as the random coding standard police. Keep the guidelines minimal and focused on being helpful, and encourage the team to talk to each other when there are issues. One very lightweight approach is to have a wiki for the team to document process, questions, etc... - and to have maybe a one-week pair programming for new recruits to learn what people actually do. This beats reading a brick of guidelines, and allows you to see the process in action and ask questions.