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

UTM (qemu on OSX) only boots into uefi shell after installing Ubuntu 22.10 (solved!)

I've been meaning to try out running Linux and Windows virtual machines on my x86 MacBook Pro using qemu . I've been using Parallels for several years. Parallels is a nice application and works well but I'm always getting bugged to purchase upgrades. Parallels provides free updates on minor version upgrades only, say 13.0 to 13.1. With so many prompts to purchase upgrades it feels like Parallels could release a bit more minor versions and a bit fewer major versions. Rather than just purchase an upgrade to Parallels I figured I'd try out qemu via the UTM application . UTM wraps qemu with a helpful gui and comes as a packages Mac application. And UTM supports both x86 and M1 systems (as qemu also supports these systems). Creating an Ubuntu VM with UTM didn't go as smoothly as with VirtualBox or Parallels but it was the settings I chose that messed me up. Here are two things I ran into when installing Ubuntu on UTM. #1. Configure the qemu instance to use a 'Display...
Post a Comment
Read more

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