Practice9.Coding Standards and Guidelines

Practice 9. Coding Standards and Guidelines

Make sure your team talks about what good code is and what coding practices team members like and dislike. Put them down on paper or in a web page and get everyone on the team to agree to them. Don't get hung up on silly formatting issues like whether curly braces should appear on the same line or next, just get everyone to agree that when they modify a file, they should follow the same formatting conventions. Having consistent coding conventions simply makes code easier to read. Plus, there is a huge benefit to having the team discuss good code and bad code; they can learn from each other and understand each other's viewpoints.

The Problem with Coding Standards and Guidelines

. . . Is that they are rarely, if ever, reread and updated by the team once they have been created. Once created, the standard is most useful for new people who join the team, so they can quickly understand some of the desirable coding traits for the project. I think this is fine, but it does reinforce the need to spend minimal time on creating the standard^[2]. You can't force people to regularly read something they already know, and there is little point in trying to continually update the document; periodic updates should be all that is required. When it comes to understanding what is good code and how to recognize bad code, the greatest value to a team is the regular good code/bad code discussions and reading through each other's code because this on-the-job collaboration helps create shared understanding and learning. The lessons learned in the on-the-job collaboration are priceless and can't be captured on paper in coding guidelines or standards.

^[2] There are many good standards online, and these could serve as an excellent starting point.

Tip: Tune Coding Guidelines to the Team

One of the teams I worked in had one coding guideline: Use whatever coding conventions you're comfortable with, but if you're modifying someone else's code, you have to follow his or her conventions.

This rule worked for that particular team because we all had many years of experience, and we each had our own coding conventions (and we were opinionated about them). We trusted each other to write good code and to be adaptable.

Our goal was simply to avoid problems like files being reformatted (to suite someone's taste who uses different conventions), variables being renamed (because of different naming conventions), and multiple conventions being used in the same file. We didn't want to waste time discussing or debating our coding conventions or making changes that had no functional purpose.