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

Graco Swing By Me - Battery to AC wall adapter modification

If you have one of these Graco battery powered swings you are probably familiar with the cost of C batteries! The swing takes four of them and they only last a handful of days. I'm not sure if the newer models support being plugged into the wall but ours didn't. If you are a little familiar with electronics and soldering, here is a rough guide on how you can modify yours to plug in! I wasn't sure how exactly to disassemble the swing side where the batteries were. I was able to open up the clamshell a bit but throughout this mod I was unable to determine how to fully separate the pieces. I suspect that there is some kind of a slip plate on the moving arm portion. The two parts of the plastic are assembled and the moving arm portion with the slip plate is slid onto the shaft. Because of the tension in that slip plate it doesn't want to back away, and because of the mechanicals that portion of the assembly doesn't appear accessible in order to free it. I was
Post a Comment
Read more

Memory efficient queuing of variable length elements

In embedded environments memory can be a critical driver of the design of data structures and containers. Computing resources have been expanding steadily each year but there are still a wide range of systems with far less than a megabyte of memory. On systems with tens of kilobytes of memory, structures are often designed to be compact to maximize data density. Rather than splurging on memory aligned elements that would be faster for the processor to access, a developer will typically use types with minimal sizes based on the known range of values that the element is intending to hold. Fixed sized buffers At my day job a fixed size pool of messages was implemented to hold message data. While this achieved one design goal of using statically allocated buffers, avoiding dynamic allocations that might fail at runtime, it isn't efficient if there is a wide range of message sizes. It isn't efficient because each message uses a message buffer. With small message sizes the buff
2 comments
Read more