Remerciez-le!

Remerciez @Admin pour avoir partagé cet document gratuitement, de la manière la plus simple, en partageant sur les réseaux sociaux.

C# Code Style Guide Version 1.0 Mark Dellacca C# Code Style Guide - II - Introd

C# Code Style Guide Version 1.0 Mark Dellacca C# Code Style Guide - II - Introduction ............................................................................................................ 1 Style Guide.............................................................................................................. 2 Source File Organization ................................................................................... 3 One Class per File .......................................................................................... 3 Ordering ........................................................................................................... 3 Namespace and Using Statements .............................................................. 3 XML Documentation ....................................................................................... 4 Class and Interface Declaration ................................................................... 4 Indentation .......................................................................................................... 6 Line Length...................................................................................................... 6 Wrapping Lines ............................................................................................... 6 Comments ........................................................................................................... 9 Implementation Comment Formats............................................................ 10 Block Comments .......................................................................................... 10 Single-Line Comments ................................................................................ 11 Trailing Comments ....................................................................................... 11 Code-Disabling Comments ......................................................................... 11 Documentation Comments ............................................................................. 13 Comment Tokens - TODO, HACK, UNDONE ................................................ 19 Declarations ...................................................................................................... 20 Number Per Line ........................................................................................... 20 Initialization ................................................................................................... 20 Placement ...................................................................................................... 20 Class and Interface Declarations ............................................................... 21 Properties ...................................................................................................... 22 Statements ........................................................................................................ 24 Simple Statements ....................................................................................... 24 Compound Statements ................................................................................ 24 return Statements ......................................................................................... 24 if, if-else, if else-if else Statements ............................................................ 24 for Statements ............................................................................................... 26 while Statements .......................................................................................... 26 do-while Statements..................................................................................... 26 switch Statements ........................................................................................ 27 try-catch Statements .................................................................................... 28 White Space ...................................................................................................... 30 Blank Lines .................................................................................................... 30 Blank Spaces ................................................................................................ 30 Naming Rules.................................................................................................... 32 Methods ......................................................................................................... 32 Variables ........................................................................................................ 32 Parameters .................................................................................................... 33 Tables ............................................................................................................. 33 C# Code Style Guide - III - Microsoft SQL Server ................................................................................... 33 General ........................................................................................................... 33 Abbreviations ................................................................................................ 34 Capitalization ................................................................................................ 34 Practices ............................................................................................................... 38 Design Rules and Heuristics .......................................................................... 39 Providing Access to Instance and Class Variables ................................. 39 Literals ........................................................................................................... 40 Variable Assignments .................................................................................. 40 Parentheses................................................................................................... 40 Parameters .................................................................................................... 41 Returning Values .......................................................................................... 41 Avoid excessive nesting using guard clause ........................................... 42 Debug Code ................................................................................................... 44 Refactoring ........................................................................................................ 45 Conclusion ............................................................................................................ 46 C# Code Style Guide - 1 - Introduction Superior coding techniques and programming practices are hallmarks of a professional programmer. The bulk of programming consists of making a large number of small choices while attempting to solve a larger set of problems. How wisely those choices are made depends largely upon the programmer's skill and expertise. This document addresses some fundamental coding techniques and provides a collection of coding practices. The readability of source code has a direct impact on how well a developer comprehends a software system, which in turn directly affects project velocity. Code maintainability refers to how easily that software system can be changed to add new features, modify existing features, fix bugs, or improve performance. Although readability and maintainability are the result of many factors, one particular facet of software development upon which all developers have an influence is coding technique. The easiest method to ensure that a team of developers will yield quality code is to establish a coding standard, which is then enforced at routine code reviews. Although the primary purpose for conducting code reviews throughout the development life cycle is to identify defects in the code, the reviews can also be used to enforce coding standards in a uniform manner. A comprehensive coding standard encompasses all aspects of code construction and, while developers should exercise prudence in its implementation, it should be closely followed. Completed source code should reflect a harmonized style, as if a single developer wrote the code in one session. Reasons for a standardize code style:  80% of the lifetime cost of a piece of software goes to maintenance.  Hardly any software is maintained for its whole life by the original author.  Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.  Your source code is a product; you need to make sure it is as well-packaged and clean. C# Code Style Guide - 2 - Style Guide C# Code Style Guide - 3 - Source File Organization One Class per File Source files should contain one class definition per source file. Said differently, each class definition will exist within its own file. The stem of the file name must be the same name as the name used in the class declaration. For example, the class definition for a class named Loan will have a file name of Loan.cs. Ordering C# source files have the following ordering: • using statements • namespace statement • Class and interface declarations Namespace and Using Statements The first non-comment lines of most C# source files are the using statements. After that, namespace statements can follow. For example: using System.Data; namespace Business.Framework; Both the using statement and the namespace statement are aligned flush against the left margin. The first letter of a component in a namespace is always capitalized. If the namespace name is an acronym, the first letter only of the namespace will be capitalized, as in System.Data.Sql. If the acronym only has two letters, both letters are capitalized, as in System.IO. C# Code Style Guide - 4 - XML Documentation Visual Studio provides for a type of documentation that the development environment is able to detect and extract to structured XML that is used to create code-level documentation that exists outside of the source code itself. XML documentation is provided for class descriptions, methods, and properties. XML documentation should be used in all circumstances where it's available. Refer to the detailed discussion on XML documentation in this document as well as in the documents provided with Visual Studio .NET. Class and Interface Declaration Sequence Part of Class / Interface Declaration Notes 1 Class / interface documentation /// <summary> /// The Person class provides… /// </summary> public class Person 2 class or interface statement 3 Fields First private, then protected, then internal and then public. 4 Properties First private, then protected, then internal and then public. 5 Constructors First private, then protected, then internal then public. Default first, then order in increasing complexity. 6 Methods Methods should be grouped by functionality rather than by scope or accessibility. For example, a private class method can be in between two public instance methods. The goal is to make C# Code Style Guide - 5 - reading and understanding the code easier. C# Code Style Guide - 6 - Indentation Indentation is constructed with tabs, not spaces. Typically, tabs are set to be displayed as white space with a width of four characters. Line Length Optimizing for down level tools and editors such as Notepad should not impact code style. 80 character lines are a recommendation, not a hard and fast rule. Wrapping Lines When an expression will not fit on a single line, break it according to these general principles: • Break after an operator. • Break after a comma. • Prefer higher-level breaks to lower-level breaks. • Indent once after a break. Here is an example of breaking a method call: SomeMethod1(longExpression1, someMethod2(longExpression2, longExpression3)); // Note: 1 indent start second line. Following are two examples of breaking an arithmetic expression. The first is preferred, since the break occurs outside the parenthesized expression, which is at a higher level. longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; // PREFER longName1 = longName2 * (longName3 + longName4 C# Code Style Guide - 7 - - longName5) + 4 * longname6; // AVOID Following is an example of indenting method declarations: SomeMethod( int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) { ... } Line wrapping for if statements should use the indent rule. For example: // USE THIS INDENTATION if ((condition1 && condition2) || (condition3 && condition4) || !(condition5 && condition6)) { DoSomethingAboutIt(); } // OR USE THIS if ((condition1 && condition2) || (condition3 && condition4) || !(condition5 && condition6)) { DoSomethingAboutIt(); } Here are two acceptable ways to format ternary expressions: C# Code Style Guide - 8 - alpha = (aLongBooleanExpression ? beta : gamma); alpha = (aLongBooleanExpression ? beta : gamma); C# Code Style Guide - 9 - Comments C# programs can have two kinds of comments: implementation comments and documentation comments. Implementation comments are those found in C++, which are delimited by /*...*/, and //. Documentation comments are C# only, and are delimited by special XML tags that can be extracted to external files for use in system documentation. Implementation comments are meant for commenting out code or for comments about the particular implementation. Doc comments are meant to describe the specification of the code, from an implementation-free perspective, to be read by developers who might not necessarily have the source code at hand. Comments should be used to give overviews of code and provide additional information that is not readily available in the code itself. Comments should contain only information that is relevant to reading and understanding the program. For example, information about how the corresponding component is built or in what directory it resides should not be included as a comment. Discussion of nontrivial or obscure design decisions is appropriate, but avoid duplicating information that is present in (and clear from) the code. It is too easy for redundant comments to get out of date. In general, avoid any comments that are likely to get out of date as the code evolves. Note: The frequency of comments sometimes reflects poor quality of code. When you feel compelled to add a comment, consider rewriting the code uploads/S4/ code-style-guide.pdf