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