Code Design & Conventions
For either a team or individual to develop clean, consistent and easily maintained code an agreement to a set of coding standards should be made by all developers.
For example, in the case of C#/.NET projects, I personally tried to adhere to the following standards:
- A consistent folder structure should be used both for development and deployment.
- Source files should have a commented header section (see sample below).
- The order of the modules in a class should be: Header, 'using' directives, Types and Constants, Data, Properties, Constructors, Destructor and then Methods. It's easier to see these sections with a comment line of dashes between them. (see sample below)
- Enums and constants should be in upper case with an underline between words,
for example:
public const int MAX_LENGTH - Most private members should be labeled protected to allow for possible inheritance in the future.
- Public members start with uppercase letters. Protected members start with lowercase letters. Words in method names and identifiers start with a capital letter (initial capped).
- Nearly all information retrieval functions should be Properties. For example, retrieving a calculated percentage level should reference the Property myObject.PercentageLevel, not call a Method myObject.GetPercentageLevel()
- Property names are initial capped copies of protected members. For example, the Property 'Count' works with the protected member 'count'.
- If a Property simply returns and stores the protected member without any manipulation, computation or database lookup, then the member should be public.
- All Class, Method and Identifier names should be self explanatory. I try to avoid cryptic or meaningless names such as 'tr5' or 'str' or 'f32r'. If a string holds someone's first name then call it 'firstName' not 'strFN'. srcTxt should be sourceText, PrtRep() should be PrintReport(). Spell it out! If you can't type, learn.
- No hanging braces on the end of lines. Matching braces should line up with each other vertically. Yea, I know it's very common - I just have a pet peeve against it.
- Indentation (tabs) should be consistent (I use two characters). Tab characters should be converted to spaces.
- Classes should be representations of 'Real World' objects or concepts. Not clumps of non-object code like 'Common', 'Globals', 'Counters' or 'Formatters'.
- Wrap all code, including property code, in try-catch exception handling. The catch block should call a global handler with options to log a message to a DB and show the User a popup.
- If any process takes longer than 1/2 second tell the User what's going on. Never let the User sit wondering if his "click" is actually doing something. Show a wait cursor at the very least.
- I understand that software development is an evolutionary process. Discoveries are made during implementation that sometimes require re-thinking an architecture. When this happens, re-write to the "new and improved" architecture. Do not try to patch or fudge a situation to work in an inadequate or deficient architecture. Have a meeting and do the re-org on the fly! Don't be lazy. Don't think your patch will save time - it will cost time!
- Above all, keep the architecture and implementation simple. Don't add features unless it's necessary. And don't add features until your code is stable and rock solid. Most programmers have heard of KISS (Keep It Simple Stupid), but I've noticed very few developers pay any attention to it.
- Don't keep adding 3rd party libraries to use one class or function. Again, don't be lazy.
//---------------------------------------------------------
//
// FILE: apple.cs
// CLASSES: Apple
//
// AUTHOR: Joe Programmer
// Copyright (c) 2015, XYZ, Inc.
// All Rights Reserved
//
// USAGE: ...
//
// NOTES: ...
//
//---------------------------------------------------------
using System;
using System.Windows;
using System.Windows.Controls;
//---------------------------------------------------------
// CLASS: Apple
// PARENT: Fruit
//---------------------------------------------------------
public class Apple : Fruit
{
//--- Types/Constants -----------------------------------
(enums, etc.)
(const, etc.)
//--- Data ----------------------------------------------
public string Color; // public member start with upper case letter
protected int size; // non-public members start with lower case letter
//--- Properties ----------------------------------------
public int Size // property names should be initial capped version of protected member
{
get
{
...
return size;
}
set
{
...
size = value;
}
}
//--- Constructor ---------------------------------------
public Apple (...)
{
...
}
//--- Method1 -------------------------------------------
public void Method1 ()
{
...
}
//--- Method2 -------------------------------------------
public void Method2 ()
{
...
}
}
I also line-up common attributes and equal signs in my code.
It's just easier to read and maintain. These two chunks are the same.
public int TotalAdjustments = 0;
protected Label prompt = new Label ();
protected ListView[] reportLists = new ListView[4];
private float customerEarnings = 0.0F;
:
:
:
public int TotalAdjustments = 0;
protected Label prompt = new Label ();
protected ListView[] reportLists = new ListView[4];
private float customerEarnings = 0.0F;
What large projects
usually end up
looking like:
usually end up
looking like:
What they should be:
