styleguide

C# at Google Style Guide

This style guide is for C# code developed internally at Google, and is thedefault style for C# code at Google. It makes stylistic choices that conform toother languages at Google, such as Google C++ style and Google Java style.

Formatting guidelines

Naming rules

Naming rules followMicrosoft’s C# naming guidelines.Where Microsoft’s naming guidelines are unspecified (e.g. private and localvariables), rules are taken from theCoreFX C# coding guidelines

Rule summary:

Code

• Names of classes, methods, enumerations, public fields, public properties,namespaces:PascalCase.
• Names of local variables, parameters:camelCase.
• Names of private, protected, internal and protected internal fields andproperties:_camelCase.
• Naming convention is unaffected by modifiers such as const, static,readonly, etc.
• For casing, a “word” is anything written without internal spaces, includingacronyms. For example,MyRpc instead ofMyRPC.
• Names of interfaces start withI, e.g.IInterface.

Files

• Filenames and directory names arePascalCase, e.g.MyFile.cs.
• Where possible the file name should be the same as the name of the mainclass in the file, e.g.MyClass.cs.
• In general, prefer one core class per file.

Organization

• Modifiers occur in the following order:public protected internal privatenew abstract virtual override sealed static readonly extern unsafe volatileasync.
• Namespaceusing declarations go at the top, before any namespaces.usingimport order is alphabetical, apart fromSystem imports which always gofirst.
• Class member ordering:
  • Group class members in the following order:
    • Nested classes, enums, delegates and events.
    • Static, const and readonly fields.
    • Fields and properties.
    • Constructors and finalizers.
    • Methods.
  • Within each group, elements should be in the following order:
    • Public.
    • Internal.
    • Protected internal.
    • Protected.
    • Private.
  • Where possible, group interface implementations together.

Whitespace rules

Developed from Google Java style.

• A maximum of one statement per line.
• A maximum of one assignment per statement.
• Indentation of 2 spaces, no tabs.
• Column limit: 100.
• No line break before opening brace.
• No line break between closing brace andelse.
• Braces used even when optional.
• Space afterif/for/while etc., and after commas.
• No space after an opening parenthesis or before a closing parenthesis.
• No space between a unary operator and its operand. One space between theoperator and each operand of all other operators.
• Line wrapping developed from Google C++ style guidelines, with minormodifications for compatibility with Microsoft’s C# formatting tools:
  • In general, line continuations are indented 4 spaces.
  • Line breaks with braces (e.g. list initializers, lambdas, objectinitializers, etc) do not count as continuations.
  • For function definitions and calls, if the arguments do not all fit onone line they should be broken up onto multiple lines, with eachsubsequent line aligned with the first argument. If there is not enoughroom for this, arguments may instead be placed on subsequent lines witha four space indent. The code example below illustrates this.

Example

usingSystem;// `using` goes at the top, outside the// namespace.namespaceMyNamespace{// Namespaces are PascalCase.// Indent after namespace.publicinterfaceIMyInterface{// Interfaces start with 'I'publicintCalculate(floatvalue,floatexp);// Methods are PascalCase// ...and space after comma.}publicenumMyEnum{// Enumerations are PascalCase.Yes,// Enumerators are PascalCase.No,}publicclassMyClass{// Classes are PascalCase.publicintFoo=0;// Public member variables are// PascalCase.publicboolNoCounting=false;// Field initializers are encouraged.privateclassResults{publicintNumNegativeResults=0;publicintNumPositiveResults=0;}privateResults_results;// Private member variables are// _camelCase.publicstaticintNumTimesCalled=0;privateconstint_bar=100;// const does not affect naming// convention.privateint[]_someTable={// Container initializers use a 22,3,4,// space indent.}publicMyClass(){_results=newResults{NumNegativeResults=1,// Object initializers use a 2 spaceNumPositiveResults=1,// indent.};}publicintCalculateValue(intmulNumber){// No line break before opening brace.varresultValue=Foo*mulNumber;// Local variables are camelCase.NumTimesCalled++;Foo+=_bar;if(!NoCounting){// No space after unary operator and// space after 'if'.if(resultValue<0){// Braces used even when optional and// spaces around comparison operator._results.NumNegativeResults++;}elseif(resultValue>0){// No newline between brace and else._results.NumPositiveResults++;}}returnresultValue;}publicvoidExpressionBodies(){// For simple lambdas, fit on one line if possible, no brackets or braces required.Func<int,int>increment=x=>x+1;// Closing brace aligns with first character on line that includes the opening brace.Func<int,int,long>difference1=(x,y)=>{longdiff=(long)x-y;returndiff>=0?diff:-diff;};// If defining after a continuation line break, indent the whole body.Func<int,int,long>difference2=(x,y)=>{longdiff=(long)x-y;returndiff>=0?diff:-diff;};// Inline lambda arguments also follow these rules. Prefer a leading newline before// groups of arguments if they include lambdas.CallWithDelegate((x,y)=>{longdiff=(long)x-y;returndiff>=0?diff:-diff;});}voidDoNothing(){}// Empty blocks may be concise.// If possible, wrap arguments by aligning newlines with the first argument.voidAVeryLongFunctionNameThatCausesLineWrappingProblems(intlongArgumentName,intp1,intp2){}// If aligning argument lines with the first argument doesn't fit, or is difficult to// read, wrap all arguments on new lines with a 4 space indent.voidAnotherLongFunctionNameThatCausesLineWrappingProblems(intlongArgumentName,intlongArgumentName2,intlongArgumentName3){}voidCallingLongFunctionName(){intveryLongArgumentName=1234;intshortArg=1;// If possible, wrap arguments by aligning newlines with the first argument.AnotherLongFunctionNameThatCausesLineWrappingProblems(shortArg,shortArg,veryLongArgumentName);// If aligning argument lines with the first argument doesn't fit, or is difficult to// read, wrap all arguments on new lines with a 4 space indent.AnotherLongFunctionNameThatCausesLineWrappingProblems(veryLongArgumentName,veryLongArgumentName,veryLongArgumentName);}}}

C# coding guidelines

Constants

• Variables and fields that can be madeconst should always be madeconst.
• Ifconst isn’t possible,readonly can be a suitable alternative.
• Prefer named constants to magic numbers.

IEnumerable vs IList vs IReadOnlyList

• For inputs use the most restrictive collection type possible, for exampleIReadOnlyCollection /IReadOnlyList /IEnumerable as inputs to methodswhen the inputs should be immutable.
• For outputs, if passing ownership of the returned container to the owner,preferIList overIEnumerable. If not transferring ownership, prefer themost restrictive option.

Generators vs containers

• Use your best judgement, bearing in mind:
  • Generator code is often less readable than filling in a container.
  • Generator code can be more performant if the results are going to beprocessed lazily, e.g. when not all the results are needed.
  • Generator code that is directly turned into a container viaToList()will be less performant than filling in a container directly.
  • Generator code that is called multiple times will be considerably slowerthan iterating over a container multiple times.

Property styles

• For single line read-only properties, prefer expression body properties(=>) when possible.
• For everything else, use the older{ get; set; } syntax.

Expression body syntax

For example:

intSomeProperty=>_someProperty

• Judiciously use expression body syntax in lambdas and properties.
• Don’t use on method definitions. This will be reviewed when C# 7 is live,which uses this syntax heavily.
• As with methods and other scoped blocks of code, align the closing with thefirst character of the line that includes the opening brace. See sample codefor examples.

Structs and classes:

• Structs are very different from classes:

  • Structs are always passed and returned by value.
  • Assigning a value to a member of a returned struct doesn’t modify theoriginal - e.g.transform.position.x = 10 doesn’t set the transform’sposition.x to 10;position here is a property that returns aVector3by value, so this just sets the x parameter of a copy of the original.

• Almost always use a class.

• Consider struct when the type can be treated like other value types - forexample, if instances of the type are small and commonly short-lived or arecommonly embedded in other objects. Good examples include Vector3,Quaternion and Bounds.

• Note that this guidance may vary from team to team where, for example,performance issues might force the use of structs.

Lambdas vs named methods

• If a lambda is non-trivial (e.g. more than a couple of statements, excludingdeclarations), or is reused in multiple places, it should probably be anamed method.

Field initializers

• Field initializers are generally encouraged.

Extension methods

• Only use an extension method when the source of the original class is notavailable, or else when changing the source is not feasible.
• Only use an extension method if the functionality being added is a ‘core’general feature that would be appropriate to add to the source of theoriginal class.
  • Note - if we have the source to the class being extended, and themaintainer of the original class does not want to add the function,prefer not using an extension method.
• Only put extension methods into core libraries that are availableeverywhere - extensions that are only available in some code will become areadability issue.
• Be aware that using extension methods always obfuscates the code, so err onthe side of not adding them.

ref and out

• Useout for returns that are not also inputs.
• Placeout parameters after all other parameters in the method definition.
• ref should be used rarely, when mutating an input is necessary.
• Do not useref as an optimisation for passing structs.
• Do not useref to pass a modifiable container into a method.ref is onlyrequired when the supplied container needs be replaced with an entirelydifferent container instance.

LINQ

• In general, prefer single line LINQ calls and imperative code, rather thanlong chains of LINQ. Mixing imperative code and heavily chained LINQ isoften hard to read.
• Prefer member extension methods over SQL-style LINQ keywords - e.g. prefermyList.Where(x) tomyList where x.
• AvoidContainer.ForEach(...) for anything longer than a single statement.

Array vs List

• In general, preferList<> over arrays for public variables, properties,and return types (keeping in mind the guidance onIList /IEnumerable /IReadOnlyList above).
• PreferList<> when the size of the container can change.
• Prefer arrays when the size of the container is fixed and known atconstruction time.
• Prefer array for multidimensional arrays.
• Note:
  • array andList<> both represent linear, contiguous containers.
  • Similar to C++ arrays vsstd::vector, arrays are of fixed capacity,whereasList<> can be added to.
  • In some cases arrays are more performant, but in generalList<> ismore flexible.

Folders and file locations

• Be consistent with the project.
• Prefer a flat structure where possible.

Use of tuple as a return type

• In general, prefer a named class type overTuple<>, particularly whenreturning complex types.

String interpolation vsString.Format() vsString.Concat vsoperator+

• In general, use whatever is easiest to read, particularly for logging andassert messages.
• Be aware that chainedoperator+ concatenations will be slower and causesignificant memory churn.
• If performance is a concern,StringBuilder will be faster for multiplestring concatenations.

using

• Generally, don’t alias long typenames withusing. Often this is a signthat aTuple<> needs to be turned into a class.
  • e.g.using RecordList = List<Tuple<int, float>> should probably be anamed class instead.
• Be aware thatusing statements are only file scoped and so of limited use.Type aliases will not be available for external users.

Object Initializer syntax

For example:

varx=newSomeClass{Property1=value1,Property2=value2,};

• Object Initializer Syntax is fine for ‘plain old data’ types.
• Avoid using this syntax for classes or structs with constructors.
• If splitting across multiple lines, indent one block level.

Namespace naming

• In general, namespaces should be no more than 2 levels deep.
• Don’t force file/folder layout to match namespaces.
• For shared library/module code, use namespaces. For leaf ‘application’ code,such asunity_app, namespaces are not necessary.
• New top-level namespace names must be globally unique and recognizable.

Default values/null returns for structs

• Prefer returning a ‘success’ boolean value and a structout value.
• Where performance isn’t a concern and the resulting code significantly morereadable (e.g. chained null conditional operators vs deeply nested ifstatements) nullable structs are acceptable.

• Notes:

  • Nullable structs are convenient, but reinforce the general ‘null isfailure’ pattern Google prefers to avoid. We will investigate aStatusOr equivalent in the future, if there is enough demand.

Removing from containers while iterating

C# (like many other languages) does not provide an obvious mechanism forremoving items from containers while iterating. There are a couple of options:

• If all that is required is to remove items that satisfy some condition,someList.RemoveAll(somePredicate) is recommended.
• If other work needs to be done in the iteration,RemoveAll may not besufficient. A common alternative pattern is to create a new containeroutside of the loop, insert items to keep in the new container, and swap theoriginal container with the new one at the end of iteration.

Calling delegates

• When calling a delegate, useInvoke() and use the null conditionaloperator - e.g.SomeDelegate?.Invoke(). This clearly marks the call at thecallsite as ‘a delegate that is being called’. The null check is concise androbust against threading race conditions.

Thevar keyword

• Use ofvar is encouraged if it aids readability by avoiding type namesthat are noisy, obvious, or unimportant.

• Encouraged:

  • When the type is obvious - e.g.var apple = new Apple();, orvarrequest = Factory.Create<HttpRequest>();
  • For transient variables that are only passed directly to other methods -e.g.var item = GetItem(); ProcessItem(item);

• Discouraged:

  • When working with basic types - e.g.var success = true;
  • When working with compiler-resolved built-in numeric types - e.g.varnumber = 12 * ReturnsFloat();
  • When users would clearly benefit from knowing the type - e.g.varlistOfItems = GetList();

Attributes

• Attributes should appear on the line above the field, property, or methodthey are associated with, separated from the member by a newline.
• Multiple attributes should be separated by newlines. This allows for easieradding and removing of attributes, and ensures each attribute is easy tosearch for.

Argument Naming

Derived from the Google C++ style guide.

When the meaning of a function argument is nonobvious, consider one of thefollowing remedies:

• If the argument is a literal constant, and the same constant is used inmultiple function calls in a way that tacitly assumes they’re the same, usea named constant to make that constraint explicit, and to guarantee that itholds.
• Consider changing the function signature to replace abool argument withanenum argument. This will make the argument values self-describing.
• Replace large or complex nested expressions with named variables.
• Consider usingNamed Argumentsto clarify argument meanings at the call site.
• For functions that have several configuration options, consider defining asingle class or struct to hold all the options and pass an instance of that.This approach has several advantages. Options are referenced by name at thecall site, which clarifies their meaning. It also reduces function argumentcount, which makes function calls easier to read and write. As an addedbenefit, call sites don’t need to be changed when another option is added.

Consider the following example:

// Bad - what are these arguments?DecimalNumberproduct=CalculateProduct(values,7,false,null);

versus:

// GoodProductOptionsoptions=newProductOptions();options.PrecisionDecimals=7;options.UseCache=CacheUsage.DontUseCache;DecimalNumberproduct=CalculateProduct(values,options,completionDelegate:null);