Live Geometry Coding Guidelines

This is a live document, please edit and add stuff as necessary. Every edit should be reviewed or discussed with the team.

Goals: the code should be uniform, consistent, readable.

Links:

Project/solution structure

File placement, file names and folder structure are very important. Carefully think when adding a new file, because changing the file structure is costly! If in doubt, ask other team members.

Tabs and indenting

Tools -> Options -> Text Editor -> Tabs -> Insert spaces, tab size = 4
Tab characters (\0x09) should not be used in code. All indentation should be done with 4 space characters. This is the default Visual Studio setting.

Curlies

Opening curly of a block should be on a new line like this:
block 
{
    stuff
}

and not like this:
block {
    stuff
}

One line flow-control statements should still include a block statement:
if (something)
{
    something else;
}

and not:
if (something)
    something else;

This enhances maintainability by ensuring that someone modifying the code at a later date will not forget to add the braces.

This style will be applied consistently to all code construct that require an open/close brace pair (classes, namespaces in C#, method block, etc.)

Commenting

It's OK to not have comments, since the code is still very much in flux. However it helps to have comments in difficult parts of the code.

Don't use obvious comments that can be inferred by just reading the code:
AssignValue(instance); // assigns a value to instance

Comments should be used to describe intention, algorithmic overview, and/or logical flow. It would be ideal, if from reading the comments alone, someone other than the author could understand a function’s intended behavior and general operation. While there are no minimum comment requirements and certainly some very small routines need no commenting at all, it is hoped that most routines will have comments reflecting the programmer’s intent and approach.

Types and members should use XML doc comments.

Spacing

Spaces improve readability by decreasing code density. Here are some guidelines for the use of space characters within code:

Do use a single space after a comma between method arguments:
Right: Console.In.Read(myChar, 0, 1);
Wrong: Console.In.Read(myChar,0,1);

Do not use a space after the parenthesis and method arguments:
Right: CreateFoo(myChar, 0, 1)
Wrong: CreateFoo( myChar, 0, 1 )

Do not use spaces between a method name and parenthesis:
Right: CreateFoo()
Wrong: CreateFoo ()

Do not use spaces inside brackets:
Right: x = dataArray[index];
Wrong: x = dataArray[ index ];

Do use a single space before flow control statements:
Right: while (x == y), if (true)
Wrong: while(x==y), if(true)

Do use a single space before and after binary operators:
Right: if (x == y), a = 2 + 3;
Wrong: if (x==y), a=2+3;

Vertical spacing:


http://blogs.msdn.com/kirillosenkov/archive/2009/03/12/kirill-s-whitespace-guidelines-for-c.aspx

Naming conventions


http://msdn2.microsoft.com/en-us/library/xzf533w0(vs.71).aspx]
Follow all .NET Framework Design Guidelines for both internal and external members. Highlights of these include:
  • Names of types, members and enums (except fields): PascalCasing
  • names of parameters, local variables and fields: camelCasing
  • NOSCREAMINGCAPS
  • nounderscoresif_possible
  • Prefix interfaces with I
  • Do not use Hungarian notation (bstrSomething, frmMain)
  • DontAbbrevLngWrdsBcseAbbrAreUsuDffcltToRd:

Use full words instead of shortened words:
expectedFilenames expFilenames
expectedMessageResourceIDs expMsgResIDs
localizedErrorMessage localizedErrMsg
modifier mod
projectReference projRef
languageOptions langOptions

Method level

Use shorter boolean conditionals:
if (X) instead of if (X == true)
if (!X) instead of if (X == false)
if (X && !Y) instead of if (X == true && Y == false)

Don't use the old C++ convention if (null == stuff), use if (stuff == null).

Type and Member design

  • Avoid using fields - use either properties or auto-properties (PascalCasing).
  • User Defined Types - we are encouraged to define and use user defined types to clearly capture the intent of the code. Don't be afraid of adding a new user defined type.

Library usage

  • Use FileInfo and DirectoryInfo instead of strings to store file and directory names
  • Use Path.Combine to concatenate parts of a path
  • Use File.ReadAllText(string) to read text from a file into a string

Last edited Apr 12, 2010 at 7:55 AM by KirillOsenkov, version 9

Comments

rharding64 Jul 27, 2010 at 4:11 AM 
concerning possible uses of Live Geometry;
i have not yet dug into it yet, but i am looking at possible application areas;
First some upfront supporting information: I am an electronic engineer who cross trained into MS .NET about 4 years ago. Since that time, my deliverables have consisted of c# windows based applications that provide remote control of connected device under test over USB/LAN and associated electronic test equipment using ivi.com .NET drivers using SCPI(see ivifoundation.org).
So, in demos that i show to employers, i have an agilent 33220A arbitrary waveform generator that i remote control over USB and LAN(LXI device) using c# 2008 express and sql server 2008 express. I have 2010 tools installed and i have been experimenting with silverlight together with ironpython and ironruby.

So, what i am looking for in the LIveGeometry is a way to model these waveforms so i can port them to webpage using silverlight. besides waveform generator test equipment i have specialized electronic hardware with both analog to digital and digital to analog capabilties on board. So, using that equipment or using the waveform generator, i want to be able to view the waveforms in my c# .NET GUI.

My application is targeted to electronic engineers who are working on new product prototypes, so it will contain a waveform editor, an equation editor for output and waveform display for both input and output.

looking for any suggestions you may have.

have a good day.

any suggestions / comments are welcome.