What is the most useful way to represent a coding standard?

Question

We currently keep our coding standard in a MSWord document under SVN.

As our standards grow / change, it's becoming an increasingly clunky beast to maintain.

Most entries currently consist of:

• A succinct explanation of the guideline.
• Reasoning behind the guideline.
• Any extra notes.
• Examples of what you should do.
• Examples of what you should not to.

At the moment we use track changes within the document to keep track of pending suggestions / corrects which are periodically reviewed and then accepted / rejected.

Is there a de-facto good way of tackling maintaining a document like this?

Answer 1

A repository at GitHub would serve well. See example: https://github.com/airbnb/javascript - you can have discussions, track changes, accept/reject pull requests, etc.

Also it would help if you use auto-formatting tools plugged into your build process like https://golang.org/cmd/gofmt/ or https://github.com/thoughtbot/hound

Answer 2

I suggest you use plain text file (or HTML / some other markup file if you need some fancy formatting) under some version control system. We used Word's features for versioning and I like what Git offers much much more.

Answer 3

• GITHUB : As an organization, if you maintain a private Github repository (not opensource, but leverage Github's strengths to maintain repository, allow distributed coding accessible to individuals within organization), you could upload your Coding Standards document to a Github repository, maintain a markdown document, which could have reviews/pull requests etc, as mentioned by Alex above

• REVIEWBOARD : If your organization does not have a private Github repository, then I suggest you could choose this option, if your organization is performing code reviews through review board. ReviewBoard allows to review code by peers, maintain data of the different reviews, whether addressed, whether the version is allowed to be shipped etc. So, you could avail this feature of review board to review Coding Standards document. ReviewBoard has a feature of reviewing PDF documents . So, I guess by this option, you are maintaining a repository for CodingStandards document as well as providing an option of reviewing PDF document, which is tracked by ReviewBoard application.

Hope it helped. I guess there might be many other ways in which many companies might be doing.