codedweller
Home • Coding Style

CODEDWELLER CODING STYLE

These style guidelines have been built up over several decades of experience writing, reading, rewriting, maintaining, and developing software in several languages. That's another way of saying they didn't come easy. Along the way we have fought about these and explored (as a team) how each point has affected us in our day-to-day work

From time to time we've all read different treatments on how source code should be formatted and we've tried just about all of them. As you can probably see in the code -- we've even changed our minds about things along the way. Improvement is a continuous process after all. In fact, we will most certainly change our minds again as time goes on.

That said-- this is the way we do things now, and the rate of change has been reduced to a negligible trickle. We hope you find these guidelines informative and useful. If you write code for us you will need to follow these guidelines. It's best (less work) to do that on your first try.

There are a lot of tricks and tips that have been learned over several decades of work and research. It will take a while to get them posted here (if we chose to do that). If you feel something is missing then ask us about it and we will clarify. In most cases you can derive the answer from what is here.


General Concepts

Be Flexible -These are guidelines, not hard rules. They are intended to nudge you in the right direction and encourage good habits. There are occasionally good reasons to stray from these guidelines. For those times there is this guideline: As much as possible these should be in order of their importance. So, if you are in a spot where you find a conflict between two (or more) guidelines then do your best to follow the more important one(s).

Be Clear - Someone who knows nothing about the code before they look at it should be able to quickly and unambiguously understand what it means.

Be Consistent - If you are working on an existing piece of code that follows a different style then make your new code consistent with the existing code. There are two ways to do that:

One way is to update the existing code (or some reasonable portion of it) to the current standard. That works best if you are making substantial changes to the old code since you're going to be testing a lot of it anyway and updating it's style would be a good way for you to become familiar with the existing code.

The other way is to write your new code so that it follows the style of the existing code. This works best if you are making a minor change or addition to the old code, or if the code actually belongs to a customer who has specified their own style rules.


Blocks, Indenting, and Margins

void function(int parameter1) {
    subfunction1(parameter1);
    subfunction2(parameter1);
}

Full Indents - Full indents are 4 spaces. Any subordinate code block requires a full indent.

void complicated(
  int firstParameter,
  int secondParameter,
int thirdParameter ) { subfunction1(firstParameter); subfunction2(secondParameter); subfunction3(thirdParameter); }

Half Indents - Half indents are used to complete the entry point of a new code block when it is long and/or complicated. In the example above there are a lot of parameters that are passed to the function. Separating each onto it's own line helps to clarify them. They are part of the function, but they are not yet part of the new code block.

Half indents are also useful in larger structures where there may be more than one part to the block. This might be a class definition, a complex constructor, or a complicated bit of logic. In general, any time where it is helpful to indent but the indentation doesn't really specify a new sub-block a half indent makes sense.

Complicated logic...

if(
  ThisIsTrue &&
  ThatIsTrue &&
  TheOtherIsTrue
  ) {
    doThisThing();
} 

Complex Constructor...

ComplexClass(SomeType& Initializer):
  SubClassA(Initializer),
  SubClassB(SomeConstantA),
  SubClassC(SomeConstantB) 
    {
    setupInternalPart(Initializer);
}

Class definition...

12345678901234567890123456789012345678901234567890123456789012345678901234567890123456789
     
class SomeClass {                                           // Special object for things

  private:

    int PartOne;
    int PartTwo;

    void calculate();                                       // Blend the parts normally
    void recalculate();                                     // Blend using special logic

  public:

    SomeClass();
    ~SomeClass();

    int adjustPartOne(int PartOneAdjustment);
    int adjustPartTwo(int PartTwoAdjustment);

    int CompositValue();
};   

Comments in the Margin - Keep running comments in the right margin aligned at the same character position. Normally running comments should begin in character position 81. However if there is a good reason to use a different position then that's ok as long as the position is consistent. In the above example there is not enough room to start any meaningful comments at 81 so they were started earlier.

It's important to keep this margin in mind even if you're not going to be writing a lot of running comments. For one thing it leaves space for annotations that might come later, or for when someone is working with the code on paper (folks still do that?). Another good reason is that it helps to constrain complexity.

Using a consistent starting point for running comments creates a kind of vertical line to separate code from descriptive prose. This imaginary line also acts as a guide to help you know when a line of code might be getting a little long (and complex).

If you find yourself writing a line of code that extends into the comment area on the right then that's a good sign that you want to reformat the line onto more than one line to make it clearer. You might even want to rework the line into more than one statement if that will make the code more obvious / clearer.

... more to come.