Skip to main content

Thoughts on Coding Standards

Having been involved in coding standards discussions at several jobs I've usually found the process to be an arbitrary exercise in codifying personal opinion. The conversation inevitably turns to pedantic things such as where to put curly braces or how to indent. I've started to think about how to try to focus teams on higher value areas of software engineering, and how to design coding standards to focus teams in these areas. This post is the product of those thoughts, written as a coding standards document.

Coding standards

Preface

The purpose of this document is to describe some software development practices. The topics are ordered according to their relative importance to our organization. Where critical, firm rules are specified; elsewhere the standards are intentionally relaxed so you have the freedom to express your personal preference. This document is intended to be a helpful tool that improves the quality of the engineering of our organization. It is not intended to be used as a literal interpretation of how to design or build something, or to codify personal preference. The standards in this document are based on technical reasoning.

Architecture

Architectural guidelines are intended to apply to all languages.

Software modules should follow these guidelines:
  • APIs should be orthogonal
    • The purpose of each method should be unique. Callers can build up complex behavior by calling multiple methods through helper functions but APIs should typically not provide multiple ways to accomplish the same thing.
  • Public APIs must be clearly documented.
  • Modules (files, classes etc) should perform a single task.
  • Modules (files, classes etc) that consist of other modules should use composition instead of inheritance

Implementation

All classes should have unit tests written against them. All unit tests should be automated where possible.

Whitespace

Adequate whitespace is necessary to make the code easier to read. If people mention your code is difficult to read they might be having trouble because there is insufficient whitespace. While the code should be concise, it can help to have white space between adjacent lines of code to indicate two separate logical sections, for instance.

Naming convention

The naming of classes, objects, variables etc, is important to the readability of the code. Names should attempt to clearly and concisely describe the purpose of the software object. Be open to constructive criticism.

Documentation

All public APIs must be documented. All private APIs should be documented as well. Depending on the intended audience you may need to adjust or expand your documentation. It is important to provide enough information that a reader can use a web search engine and your existing comments in order to research the details of your implementation. Hyperlinks in your comments can be helpful.

Coding style

Coding style is one of the easiest things to define. It is easy to specify the number of spaces before a curly brace or the number of spaces or tabs to indent given lines. Programmers tend to gravitate to coding style because, like logic, it is something that can be defined. It is important to realize that most coding style is personal preference. It may be useful to pick an arbitrary coding style for your organization so the group will produce consistently formatted code. If you've chosen an arbitrary style simply for consistency, it helps to state explicitly that the convention is arbitrary in order to allow for the style convention to evolve over time. Indicating that the coding style is arbitrary also makes it clear that there are more important areas of the coding conventions.

Coding style should follow these conventions:
  • Consistency within a language that specifies a convention. Eg. .NET design guidelines or the Python style guide
  • Consistency within a software application
  • A programmer is permitted to use a coding style within a software application provided that
    • It is a generally accepted convention, eg. K&R style
    • Other developers do not find the code difficult to read
    • It is maintained throughout that application
  • Consistency within files
    • Style should be maintained in individual files. This applies to existing as well as 3rd party code. Changes to style are permitted but should be discussed and performed as an atomic change, for example one patch to reformat an entire file.

References

Richard Rodger http://www.richardrodger.com/2012/11/03/why-i-have-given-up-on-coding-standards/
Labels:

Comments

Post a Comment

Popular posts from this blog

Debugging an imprecise bus access fault on a Cortex-M3

This information may apply to other cortex series processors but is written from practical experience with the Cortex-M3. Imprecise bus access faults are ambiguous, as noted by the term "imprecise". Compared to precise bus errors, imprecise errors are much trickier to debug and especially so without a deep understanding of arm processors and assembly language. Imprecise and precise flags are found in the BusFault status register, a byte in the CFSR (Configurable Fault Status Register). BusFault status register bits The definition for imprecise and precise bits is: [2] IMPRECISERR Imprecise data bus error: 0 = no imprecise data bus error 1 = a data bus error has occurred, but the return address in the stack frame is not related to the instruction that caused the error. When the processor sets this bit to 1, it does not write a fault address to the BFAR. This is an asynchronous fault. Therefore, if it is detected when the priority of the current pr...
5 comments
Read more

Travelling on Spirit airlines out of Boston Logan airport? Here are some tips.

I attended CES 2017 in Las Vegas. Booking the trip late I ended up on Spirit airlines. It was both non-stop, making it six hours to Las Vegas from Boston, and affordable, less than $300 for a one way trip compared to around $700 with JetBlue. Here are some tips that might help you when travelling on Spirit from Boston Logan airport. Eat Spirit is located in the B-terminal, gates B-37 and 38, with its own TSA security checkpoint. While it does have restrooms and places to sit the food selection is limited to a single food stand. I'd recommend eating at the Legal C Bar (number 77 in the image below) prior to going through the terminal security checkpoint. The food and service there were great. Drink The water and other drinks are cheaper if you buy them at the food cart rather than on the flight. Seats The seats on Spirit don't recline. They do this to reduce weight, seat cost, seat maintenance costs, and so seats don't impact the free space of other passengers,...
3 comments
Read more

Yocto recipe SRC_URI for a BitBucket / GitHub ssh git repository

This is a particularly geeky post but because Google searches didn't turn up any information I thought it would be helpful to document the issue and solution for others. I was writing  Yocto recipes that pulled from BitBucket git repositories in ssh form and ran into several issues getting a SRC_URI that worked. GitHub uses the same syntax for their ssh repositories. A BitBucket / GitHub git url, in ssh form, looks like: < username >@bitbucket.org:< account name >/< repository name >.git a more concrete example for a git repository in one of my BitBucket accounts looks like: git@bitbucket.org:cmorgan/somerepository.git Yocto recipes can pull from git repositories by setting the SRC_URI variable appropriately. Unfortunately you can't just do: SRC_URI = "git@bitbucket.org:cmorgan/somerepository.git You'll get errors because the Yocto won't know what kind of url this is. You need to specify the protocol for Yocto to k...
2 comments
Read more