11
Jun
12

My Coding Style

I think that coding style is important, although not at the expense of good code. This is going to be a rare post where it is mostly opinion. I feel that different languages need different approaches to coding style so I have included a few specifics here too.

General

I have a few points which I stick to across all languages because I feel they are useful to properly readable and therefore maintainable code. Many of these are inherited from the C++ standard used at my workplace. Here are the main imporatant points:

  • Descriptive names. My naming convention is CamelCase for class names and lowercase_with_undescores for function/variable names.
  • 2 space indenting.
  • 79 character line limit.
  • A history section at the top of files and functions as detailed below.
  • Prefixed member variables with m_ and static variables with s_

One thing I also do is break up functions or sections of a file using a line of equals signs or dashes as can be seen in any of my files.

History

I think that a history of changes is important, even for personal scripts and utilities. This is so you can see what has changed and why, and while you cannot instantly revert like you can with version control, it makes recovering changes much easier. Personally my history sections (in C++) look like this example:

//=============================================================================
// Conways Game of Life
//
// Written by: David Corne (DGC)
// Edited by:
//
// History
// Who When     What
// --- -------- ---------------------------------------------------------------
// DGC 26/10/11 Written.
// DGC 07/11/11 Changed file name to class name
//-----------------------------------------------------------------------------
//

This is rather formal as I normally don’t leave a Who section or Edited by for files I feel I’m just going to work on myself.

C++

As this is my main language I don’t really have much to say extra about it because it is where I get my coding style from. However specific to C++ is the top of my header files which I use for organising pre-declarations etc.

//=============================================================================
// <name>
//
//  <Full description.>
//

#ifndef _<name>_H
#define _<name>_H
// class predeclarations to avoid header file inclusion

// types: classes, enums, typedefs
// variables: consts, statics, exported variables (declared extern elsewhere)
// local forward function declarations

//=============================================================================
class <name>

Also worth mentioning is the fact that I use .C files rather than .cpp. This is because that is what is done at work as the codebase pre-dates the .cpp extension.

Python

For Python I do not stick to my naming of member variables convention. This is because in classes the variables are called like so self.member the m_ prefix like this self.m_member seems superfluous as it is implied. Also as all members are public I did not like the idea of calling code like object.m_member = value as it looks like you are setting private member variables. Another difference is that I use 4 space indentation rather than 2 space, this is mainly to make indentation more obvious but also as this is recommended in the PEP 8 – Style Guide for Python.

Lisp

As an emacs user I have become acquainted with elisp and written a few of my own customisations and functions (the site mastering emacs has been very helpful for this). I don’t have much to say about coding style for lisp and it’s various dialects other than this: While most lispers like a long stack of closing brackets at the end of a line, I feel that they should be closed on separate lines so that you can more clearly see the equivalent of the scope. I think this makes the code much clearer to read and thus more maintainable. Here is a function I wrote to evaluate the current line.

;; ============================================================================
(defun dgc-eval-line ()
  "Evaluates the current line"
  ;;
  ;; History
  ;; When     What
  ;; -------- -----------------------------------------------------------------
  ;;~15/01/12 Written
  ;; 26/01/12 Added History
  ;; 27/01/12 Use save-excursion
  ;;---------------------------------------------------------------------------
  (interactive)
  (save-excursion
    (beginning-of-line)
    (let ((beg (point)))
      (end-of-line)
      (eval-region beg (point))
      )
    )
  )

Unfortunately WordPress doesn’t support Lisp. This is the closest dialect I could find for syntax highlighting, as none of the supported languages use ; for comments.

Advertisements

2 Responses to “My Coding Style”


  1. 1 stevehuston
    July 5, 2012 at 3:20 pm

    Great advice, Dave… particularly the 79 char line limit. I am a long-time emacs user from the VT100 era and still use terminal-width windows to edit in, so when I open a file that someone with a full wide-screen window worked on last, and used the whole screen, I hate the wrap-arounds.

    Sometimes you have to break the rule due to the sheer length of a line that would be too awkward an unclear to break and re-indent, but that’s the nature of rules…

    • July 5, 2012 at 3:28 pm

      Thanks 🙂 I agree with the breaking of the rules, I find I most often have to do this with Python due to the fact that indentation matters.

      On another note there is a nice emacs package called whitespace, in which one of the features is showing long lines. It has a default length of 80 and it just highlights the part of the line over the required length.
      This is the entry from my .myemacs for it which also shows tabs:

      ;; change the colour and enable whitespace long lines
      (require 'whitespace)
      (setq whitespace-style '(face tabs lines-tail))
      (setq whitespace-line-column 79)
      (global-whitespace-mode t)


What did you think?

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


%d bloggers like this: