How do you document your coding standards?

Question

What have you found to be the best way to publish your coding standards and why?

Answer 1

If you mean Style Guidelines - a Word document or PDF. IMO, this is something that is "set in stone", but on a per-project basis (if you see something that doesn't work, fix it for the next project, especially if it's late in the project and you have a ton of code that follows the existing style).

Answer 2

Our project is mostly in python, so we basically took the Python Coding Guidelines, changed something here and there that we didn't like, and stuck them up on our Trac wiki. It's linked right on the front page so that devs know where to find it. So far it has actually done a pretty decent job of being followed!

Answer 3

Code guidelines is a company-wide document describing practices. And it is available and must be quite strictly followed.

Code formatting standard is subject to decide between a team (or project) members. For our project, it is kept in SVN as a set of settings for Resharper plugin.

Answer 4

We use our code to document the standard. This along side with enforcement from the senior/lead engineers has worked great for us. The reason we don't maintain an actual document is because we've found that nobody reads it and it becomes outdated rather fast.

IMHO all it takes to prove the point is existing code that shows what the style/standard.

Travel light!

Answer 5

For the initial process, a wiki prepared with sub-headings is useful to gather opinions from various developers. Once feedback has been gathered, it can then be tidied up and "published".

Answer 6

I document the code standard by:

• structure from the most important general style (like indentation, line wrapping, braces, ... )
• to the less visible details (space before/after ( or ) )
• code examples
• setting descriptions to configure the eclipse code formatter
• prosa

Answer 7

Whenver I've been responsible for setting a coding standard I try and find a good one on the internet that suits our needs and use that. I'll take whatever format it comes in, usually PDF or Word.

There's no point re-inventing the wheel -- I may as well leverage the hard work someone else has done.

Answer 8

When I managed a small team, our "coding standards" was a wrapper script on CVS that ran indent (with a team-wide rc file) on your code as you checked it in.

Answer 9

An in-house website with SVN used to managing the changes works. The 'latest' is always available to the team online.

Answer 10

We put it on the wiki, with links to code snippets where this is helpful.

We then set up a code formatter in Eclipse to match as close as possible to this coding standard, although that cannot help with best-practice coding methodologies.

Answer 11

I think the best way is to use Checkstyle to enforce your coding standard and assure that the build fail if some code something against the checkstyle rules.

Then use code review and pair programming so that juniors can learn from the seniors

You could also setup a wiki page.

Answer 12

The only effective way to publish a coding standard in my opinion is to integrate it in the ide used by the developers (eclipse or idea for example). So new code will follow the standards out of the box and old code may be reformatted using the ide.

Only few developer will read coding standards, fewer of them will use them afterwards...

Answer 13

If you are developing in .NET. I would recommend using StyleCop to check your builds. I would also recommend using ReSharper and the StyleCop plugin.

With ReSharper and the StyleCop plugin you get red "squiggly" lines under code that is against the standard and a simple mouse over will explain why. No code reviews, no docs to maintian.

Using StyleCop in your build process will ensure that all code checked-in conforms to the standards.

Answer 14

We moved from Word documents which proved to be cumbersome and prone to become obsolete to

• Wiki pages with the standards and examples
• Automatic coding standard validation tools running during CI process

N.B. Also we have a client who does not use run anything aside from the build itself in CI cycle. They keep their rules in the ReSharper and are quite pleased with the results

Answer 15

If you are using Eclipse, you can use formatters (Preferences->Java->Code Style->Formatters) to automatically format code when the source file is saved. We simply have our company's formatter available on our wiki and everyone imports it into Eclipse.

The cool thing about formatters is that you can decide which one you want to use so you can have different projects with different formats. However, we typically only use one format so our code is uniform across all projects.

Answer 16

We use the following:

1. Tools/plugins in the editor (checkstyle, pmd, in-house tools)
2. Build time checks produce a report.
3. The wiki is used to document code review comments
4. From 3, we then refactor the 'toolable' ones into the in-house tool.

Answer 17

It depends on the circumstances:

I worked in a small company with only three developers. There, we just talked it out. This means nothing more than asking your co-developers, if in doubt about the coding style. After a while, someone realized, that the same questions were asked several times and opened a coding-standard page in our wiki.

Today I work in a small research lab. In this particular field, we do not have formal coding standards. However, as we work in teams and do pair sessions regularly, an implicit coding standard seems to appear from nowhere.

---

From some friends, who develop systems for aircraft guidance, I know that they agree on coding standards based on

• security and government restrictions
• needs and inputs from the QA department
• if there is still any freedom of choice: input from the developers

This coding standard is written down and is enforced by QA.

Answer 18

We currently have the coding standard in a Wiki that only the Sr. Developers have rights to edit. However, like many people have already stated, no one reads it after their first few days. We are currently in the process of trying to get our coding standard into StyleCop on the .NET side. The Delphi stuff is a little harder since we don't have a Delphi framework like StyleCop to use.

Answer 19

I do everything to make it easy to apply for everyone:

• first of all, everyone in the team should agree to apply them
• I share setting for used editors (gvim, emacs ...)
• I provide empty source file with the boilerplate heading
• I sumarize the standard on a single reference sheet, not showing the rules but a piece of code properly formatted as standardized

Answer 20

We have done the following to document our coding standards:

1. Wrote them down in a plain word file. The base for this styleguide was the Sun Coding Conventions.
2. Configured Checkstyle and PMD to follow these coding conventions, additionally provided a default workspace for Eclipse that had the right configuration that fits to the defined Checkstyle and PMD configurations.
3. Added three chapters to our coding conventions that explained what Checkstyle, PMD and Eclipse configuration fullfilled which part of the styleguide, so that each architect could modify the styleguide and the configurations of Checkstyle, PMD and Eclipse.
4. Developed little plugins so that by installing Checkstyle and PMD together with our plugins, our coding convention defined by Checkstyle and PMD were the default and easy to select.

We think that it helps a lot not only to write it down, but to integrate it in the development environment. On the other hand, we do that only for Eclpise, because it is too much to do if you want that for each and every IDE on earth.