הבדלים

כאן מוצגים ההבדלים בין הגרסה שנבחרה והגרסה הנוכחית של הדף.

--- he:dokuwiki [2013-07-27 00:36] – 79.182.145.170
+++ he:dokuwiki [2015-12-20 23:54] (הגרסה הנוכחית) – נמחק ach
@@ שורה 1: / שורה 1: @@
-<div dir="rtl" lang="HE">
-קונבנציות קוד מטרתן ליצור אחידות בעת כתיבת קוד מקור של ספריות או אפליקציות ובכך להקל על הקריאות והתמיכתיות של קוד המקור בהווה ובעתיד. להלן הגדרת הצורך בשמירה על קונבנציות קוד אחידות (מתוך ויקיפדיה):
-</div>
-<div dir="ltr" lang="EN">
-<blockquote class="toccolours" style="float:none; padding: 10px 15px 10px 15px; display:table;">
-Coding conventions are a set of guidelines for a specific programming language that recommend programming style, practices and methods for each aspect of a piece program written in this language. These conventions usually cover file organisation, indentation,comments, declarations, statements, white space, naming conventions, programming practices, programming principles,programming rules of thumb, architectural best practices, etc. These are guidelines for software structural quality. Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Coding conventions are only applicable to the human maintainers and peer reviewers of a software project. Conventions may be formalised in a documented set of rules that an entire team or company follows, or may be as informal as the habitual coding practices of an individual. Coding conventions are not enforced by compilers. As a result, not following some or all of the rules has no impact on the executable programs created from the source code.
-</blockquote>
-</div>
-<div dir="rtl" lang="HE">
-בתי תוכנה שונים יוצרים עבור עצמם סט של חוקים וכללים מנחים התואמים את התרבות הארגונית, סביבת הפיתוח ואופי המוצרים אותם הם מפתחים. האינטרנט מלא במסמכים המסכמים קונבנציות אלה, אך כאמור כל ארגון שונה מזולתו ועל-כן לא קיימת גירסא אחד וייחודית של קונבנציות אלה עבור שפה / סביבת פיתוח מסוימת. חשוב לציין כי האכיפה של כללים אלה היא בראש ובראשונה עניין תרבותי וחברתי, אך קיימים כלים שונים העוזרים בשמירה על עמידה בסט החוקים המקובל.
-ערך זה בא להציג את אוסף הכללים והקונבציות המרכיבות את הקונבנציות הקוד של הענף. כללים אלה מקיפים תחומים רבים של פיתוח קוד, החל מקונבנצית השמות של משתנים ומחלקות ועד לצורת הכינון וסידור קבצי קוד המקור.
-תוכן הערך הנ"ל מבוסס על הספר "Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries" של Krzysztof Cwalina ו-Brad Abrams, ועל המדריך הרשמי של MSDN לבניית API-ים בשם "Framework Design Guidelines".
-</div>
-<div dir="ltr" lang="EN">
-== Naming Conventions ==
-Naming guidelines provide guidance on selecting appropriate identifiers for the elements that make up class libraries including assemblies, namespaces, types, members, and parameters. Choosing identifiers that conform to these guidelines improves the usability of your library and encourages users to trust that your library will not require learning a new set of conventions.
-To provide a consistent developer experience, these guidelines are required for publicly exposed elements such as public classes and protected methods. However, for consistency throughout your code and improved maintainability, you should consider using these conventions consistently throughout your code.
-The guidelines are organised as simple recommendations prefixed with the terms '''Do''', '''Consider''', '''Avoid''', and '''Do not'''. These guidelines are intended to help class library designers understand the trade-offs between different solutions. There might be situations where good library design requires that you violate these design guidelines. Such cases should be rare, and it is important that you have a clear and compelling reason for your decision.
-=== General ===
-This section describes general naming conventions that relate to word choice, guidelines on using abbreviations and acronyms, and recommendations on how to avoid using language-specific names.
-==== Word Choice ====
-*√ DO choose easily readable identifier names.
-For example, a property named <code>HorizontalAlignment</code> is more English-readable than <code>AlignmentHorizontal</code>.
-*√ DO favor readability over brevity.
-The property name <code>CanScrollHorizontally</code> is better than <code>ScrollableX</code> (an obscure reference to the X-axis).
-*X DO NOT use underscores, hyphens, or any other non-alphanumeric characters.
-*X DO NOT use Hungarian notation.
-*X AVOID using identifiers that conflict with keywords of widely used programming languages.
-According to Rule 4 of the Common Language Specification (CLS), all compliant languages must provide a mechanism that allows access to named items that use a keyword of that language as an identifier. C#, for example, uses the @ sign as an escape mechanism in this case. However, it is still a good idea to avoid common keywords because it is much more difficult to use a method with the escape sequence than one without it.
-==== Abbreviations and Acronyms ====
-*X DO NOT use abbreviations or contractions as part of identifier names.
-For example, use <code>GetWindow</code> rather than <code>GetWin</code>.
-*X DO NOT use any acronyms that are not widely accepted, and even if they are, only when necessary.
-==== Language-Specific Names ====
-*√ DO use semantically interesting names rather than language-specific keywords for type names.
-For example, <code>GetLength</code> is a better name than <code>GetInt</code>.
-*√ DO use a generic CLR type name, rather than a language-specific name, in the rare cases when an identifier has no semantic meaning beyond its type.
-*√ DO use a common name, such as ''value'' or ''item'', rather than repeating the type name, in the rare cases when an identifier has no semantic meaning and the type of the parameter is not important.
-Do use a generic common language runtime (CLR) type name, rather than a language-specific name, in the rare cases when an identifier has no semantic meaning beyond its type.
-For example, a method that converts data to <code>Int16</code> should be named <code>ToInt16</code>, not <code>ToShortbecause</code> Short is the language-specific type name for Int16.
-=== Capitalization Conventions ===
-The guidelines in this chapter lay out a simple method for using case that, when applied consistently, make identifiers for types, members, and parameters easy to read.
-==== Identifiers ====
-To differentiate words in an identifier, capitalize the first letter of each word in the identifier. Do not use underscores to differentiate words, or for that matter, anywhere in identifiers. There are two appropriate ways to capitalize identifiers, depending on the use of the identifier:
-*PascalCasing
-*camelCasing
-The PascalCasing convention, used for all identifiers except parameter names, capitalizes the first character of each word (including acronyms over two letters in length), as shown in the following examples: <code> PropertyDescriptor</code>
-A special case is made for two-letter acronyms in which both letters are capitalized, as shown in the following identifier: <code>IOStream</code>
-The camelCasing convention, used only for parameter names, capitalizes the first character of each word except the first word, as shown in the following examples. As the example also shows, two-letter acronyms that begin a camel-cased identifier are both lowercase: <code>propertyDescriptor</code>, <code>ioStream</code> and <code>htmlTag</code>.
-*√ DO use PascalCasing for all public member, type, and namespace names consisting of multiple words.
-*√ DO use camelCasing for parameter names.
-The following table describes the capitalization rules for different types of identifiers.
-{| class="wikitable sortable"
-|-
-! Identifier !! Casing !! Example
-|-
-| Namespace || Pascal  ||  <source lang=Csharp enclose=none>namespace System.Security { ... }</source>
-|-
-| Type || Pascal  ||  <source lang=Csharp enclose=none>public class StreamReader { ... }</source>
-|-
-| Interface || Pascal  ||  <source lang=Csharp enclose=none>public interface IEnumerable { ... }</source>
-|-
-| Method || Pascal  ||  <source lang=Csharp enclose=none>public class Object {
-public virtual string ToString();
-}</source>
-|-
-| Property || Pascal  ||  <source lang=Csharp enclose=none>public class String {
-public int Length { get; }
-}</source>
-|-
-| Event || Pascal  ||  <source lang=Csharp enclose=none>public class Process {
-public event EventHandler Exited;
-}</source>
-|-
-| Field || Pascal  ||  <source lang=Csharp enclose=none>public class MessageQueue {
-public static readonly TimeSpan
-InfiniteTimeout;
-}
-public struct UInt32 {
-public const Min = 0;
-}</source>
-|-
-| Enum value || Pascal  ||  <source lang=Csharp enclose=none>public enum FileMode {
-Append,
-...
-}</source>
-|-
-| Parameter || Camel  || <source lang=Csharp enclose=none>public class Convert {
-public static int ToInt32(string value);
-}</source>
-|}
-==== Capitalizing Compound Words and Common Terms ====
-Most compound terms are treated as single words for purposes of capitalization.
-*X DO NOT capitalize each word in so-called closed-form compound words.
-These are compound words written as a single word, such as endpoint. For the purpose of casing guidelines, treat a closed-form compound word as a single word.
-==== Case Sensitivity ====
-Languages that can run on the CLR are not required to support case-sensitivity, although some do. Even if your language supports it, other languages that might access your framework do not. Any APIs that are externally accessible, therefore, cannot rely on case alone to distinguish between two names in the same context.
-*X DO NOT assume that all programming languages are case sensitive. They are not. Names cannot differ by case alone.
-=== Names of Assemblies and DLLs ===
-An assembly is the unit of deployment and identity for managed code programs. Although assemblies can span one or more files, typically an assembly maps one-to-one with a DLL. Therefore, this section describes only DLL naming conventions, which then can be mapped to assembly naming conventions.
-*√ DO choose names for your assembly DLLs that suggest large chunks of functionality, such as System.Data.
-Assembly and DLL names don’t have to correspond to namespace names, but it is reasonable to follow the namespace name when naming assemblies. A good rule of thumb is to name the DLL based on the common prefix of the assemblies contained in the assembly. For example, an assembly with two namespaces, <code>MyCompany.MyTechnology.FirstFeature andMyCompany.MyTechnology.SecondFeature</code>, could </code>be called <code>MyCompany.MyTechnology.dll</code>.
-*√ CONSIDER naming DLLs according to the following pattern: <code><Company>.<Component>.dll</code>, where <code><Component></code> contains one or more dot-separated clauses. For example: <code>Litware.Controls.dll</code>.
-=== Names of Namespaces ===
-As with other naming guidelines, the goal when naming namespaces is creating sufficient clarity for the programmer using the framework to immediately know what the content of the namespace is likely to be. The following template specifies the general rule for naming namespaces:
-<code><Company>.(<Product>|<Technology>)[.<Feature>][.<Subnamespace>]</code>
-The following are examples:
-<code>Fabrikam.Math Litware.Security</code>
-*√ DO prefix namespace names with a company name to prevent namespaces from different companies from having the same name.
-*√ DO use a stable, version-independent product name at the second level of a namespace name.
-*X DO NOT use organisational hierarchies as the basis for names in namespace hierarchies, because group names within corporations tend to be short-lived. Organise the hierarchy of namespaces around groups of related technologies.
-*√ DO use PascalCasing, and separate namespace components with periods (e.g.,Microsoft.Office.PowerPoint). If your brand employs nontraditional casing, you should follow the casing defined by your brand, even if it deviates from normal namespace casing.
-*√ CONSIDER using plural namespace names where appropriate.
-For example, use <code>System.Collections</code> instead of <code>System.Collection</code>. Brand names and acronyms are exceptions to this rule, however. For example, use <code>System.IO</code> instead of <code>System.IOs</code>.
-*X DO NOT use the same name for a namespace and a type in that namespace.
-For example, do not use Debug as a namespace name and then also provide a class named Debugin the same namespace. Several compilers require such types to be fully qualified.
-==== Namespaces and Type Name Conflicts ====
-*X DO NOT introduce generic type names such as <code>Element</code>, <code>Node</code>, <code>Log</code>, and <code>Message</code>.
-There is a very high probability that doing so will lead to type name conflicts in common scenarios. You should qualify the generic type names (<code>FormElement</code>, <code>XmlNode</code>, <code>EventLog</code>, <code>SoapMessage</code>).
-There are specific guidelines for avoiding type name conflicts for different categories of namespaces.
-*'''Application model namespaces''' - Namespaces belonging to a single application model are very often used together, but they are almost never used with namespaces of other application models. For example, the <code>System.Windows.Forms</code> namespace is very rarely used together with the <code>System.Web.UI</code> namespace. The following is a list of well-known application model namespace groups: <code>System.Windows*</code>, <code>System.Web.UI*</code>.
-**X DO NOT give the same name to types in namespaces within a single application model. For example, do not add a type named Page to the <code>System.Web.UI.Adapters</code> namespace, because the <code>System.Web.UI</code> namespace already contains a type named Page.
-*'''Infrastructure namespaces''' - This group contains namespaces that are rarely imported during development of common applications. For example, .Design namespaces are mainly used when developing programming tools. Avoiding conflicts with types in these namespaces is not critical.
-*'''Core namespaces''' - Core namespaces include all System namespaces, excluding namespaces of the application models and the Infrastructure namespaces. Core namespaces include, among others, <code>System</code>, <code>System.IO</code>, <code>System.Xml</code>, and <code>System.Net</code>.
-**X DO NOT give types names that would conflict with any type in the aCore namespaces. For example, never use <code>Stream</code> as a type name. It would conflict with <code>System.IO.Stream</code>, a very commonly used type.
-*'''Technology namespace groups''' - This category includes all namespaces with the same first two namespace nodes (<code><Company>.<Technology>*</code>), such as <code>Microsoft.Build.Utilities</code> and <code>Microsoft.Build.Tasks</code>. It is important that types belonging to a single technology do not conflict with each other.
-**X DO NOT assign type names that would conflict with other types within a single technology.
-**X DO NOT introduce type name conflicts between types in technology namespaces and an application model namespace (unless the technology is not intended to be used with the application model).
-=== Names of Classes, Structs, and Interfaces ===
-The naming guidelines that follow apply to general type naming.
-*√ DO name classes and structs with nouns or noun phrases, using PascalCasing.
-This distinguishes type names from methods, which are named with verb phrases.
-*√ DO name interfaces with adjective phrases, or occasionally with nouns or noun phrases.
-Nouns and noun phrases should be used rarely and they might indicate that the type should be an abstract class, and not an interface.
-*X DO NOT give class names a prefix (e.g., "C").
-*√ CONSIDER ending the name of derived classes with the name of the base class.
-This is very readable and explains the relationship clearly. Some examples of this in code are: <code>ArgumentOutOfRangeException</code>, which is a kind of <code>Exception</code>, and <code>SerializableAttribute</code>, which is a kind of <code>Attribute</code>. However, it is important to use reasonable judgment in applying this guideline; for example, the Button class is a kind of Control event, although Control doesn’t appear in its name.
-*√ DO prefix interface names with the letter I, to indicate that the type is an interface.
-For example, <code>IComponent</code> (descriptive noun), <code>ICustomAttributeProvider</code> (noun phrase), and <code>IPersistable</code> (adjective) are appropriate interface names. As with other type names, avoid abbreviations.
-*√ DO ensure that the names differ only by the "I" prefix on the interface name when you are defining a class–interface pair where the class is a standard implementation of the interface.
-====  Name of Generic Type Parameters ====
-*√ DO name generic type parameters with descriptive names unless a single-letter name is completely self-explanatory and a descriptive name would not add value.
-*√ CONSIDER using T as the type parameter name for types with one single-letter type parameter.
-<source lang=csharp enclose=pre>public int IComparer<T> { ... }
-public delegate bool Predicate<T>(T item);
-public struct Nullable<T> where T:struct { ... }
-</source>
-*√ DO prefix descriptive type parameter names with T.
-<source lang=csharp enclose=pre>public interface ISessionChannel<TSession> where TSession : ISession
-{
-    TSession Session { get; }
-}
-</source>
-*√ CONSIDER indicating constraints placed on a type parameter in the name of the parameter.
-For example, a parameter constrained to <code>ISession</code> might be called <code>TSession</code>.
-==== Names of Common Types ====
-*√ DO follow the guidelines described in the following table when naming types derived from or implementing certain .NET Framework types.
-{| class="wikitable sortable"
-|-
-! Base Type!! Derived/Implementing Type Guideline
-|-
-| <code>System.Attribute</code> || √ DO add the suffix "Attribute" to names of custom attribute classes. add the suffix "Attribute" to names of custom attribute classes.
-|-
-| <code>System.Delegate </code> || √ DO add the suffix "EventHandler" to names of delegates that are used in events.
-√ DO add the suffix "Callback" to names of delegates other than those used as event handlers.
-X DO NOT add the suffix "Delegate" to a delegate.
-|-
-| <code>System.EventArgs</code> || √ DO add the suffix "EventArgs.”
-|-
-|<code>System.Enum</code> || X DO NOT derive from this class; use the keyword supported by your language instead; for example, in C#, use the enum keyword.
-X DO NOT add the suffix "Enum" or "Flag.”
-|-
-| <code>System.Exception</code> ||√ DO add the suffix "Exception.”
-|-
-| <code>IDictionary, IDictionary<TKey,TValue></code> || √ DO add the suffix "Dictionary." Note that <code>IDictionary</code> is a specific type of collection, but this guideline takes precedence over the more general collections guideline that follows.
-|-
-| <code>IEnumerable, ICollection, IList, IEnumerable<T>, ICollection<T>, IList<T></code> || √ DO add the suffix "Collection.”
-|-
-| <code>System.IO.Stream</code> || √ DO add the suffix "Stream.”
-|-
-| <code>CodeAccessPermission, IPermission</code> || √ DO add the suffix "Permission.”
-|}
-==== Naming Enumerations ====
-Names of enumeration types (also called enums) in general should follow the standard type-naming rules (PascalCasing, etc.). However, there are additional guidelines that apply specifically to enums.
-*√ DO use a singular type name for an enumeration unless its values are bit fields.
-*√ DO use a plural type name for an enumeration with bit fields as values, also called flags enum.
-*X DO NOT use an "Enum" suffix in enum type names.
-*X DO NOT use "Flag" or “Flags" suffixes in enum type names.
-*X DO NOT use a prefix on enumeration value names (e.g., "ad" for ADO enums, "rtf" for rich text enums, etc.).
-==== Interop Classes ====
-Classes that are there for interop wrappers (<code>DllImport</code> statements) should follow the naming convention below:
-*'''NativeMethods''' – No suppress unmanaged code attribute, these are methods that can be used anywhere because a stack walk will be performed.
-*'''UnsafeNativeMethods''' – Has suppress unmanaged code attribute. These methods are potentially dangerous and any caller of these methods must do a full security review to ensure that the usage is safe and protected as no stack walk will be performed.
-*'''SafeNativeMethods''' – Has suppress unmanaged code attribute. These methods are safe and can be used fairly safely and the caller isn’t needed to do full security reviews even though no stack walk will be performed.
-Examples:
-<source lang=csharp enclose=pre>class NativeMethods
-{
-   private NativeMethods() {}
-   [DllImport(“user32”)]
-   internal static extern void FormatHardDrive(string driveName);
-}
-[SuppressUnmanagedCode]
-class UnsafeNativeMethods
-{
-   private UnsafeNativeMethods() {}
-   [DllImport(“user32”)]
-   internal static extern void CreateFile(string fileName);
-}
-[SuppressUnmanagedCode]
-class SafeNativeMethods
-{
-   private SafeNativeMethods() {}
-   [DllImport(“user32”)]
-   internal static extern void MessageBox(string text);
-}
-</source>
-All interop classes must be '''private''', and all methods must be '''internal'''. In addition a private constructor should be provided to prevent instantiation.
-=== Names of Type Members ===
-Types are made of members: methods, properties, events, constructors, and fields. The following sections describe guidelines for naming type members.
-==== Names of Methods ====
-Because methods are the means of taking action, the design guidelines require that method names be verbs or verb phrases. Following this guideline also serves to distinguish method names from property and type names, which are noun or adjective phrases.
-*√ DO give methods names that are verbs or verb phrases.
-<source lang=csharp enclose=pre>public class String {
-     public int CompareTo(...);
-     public string[] Split(...);
-     public string Trim();
-}</source>
-==== Names of Properties ====
-Unlike other members, properties should be given noun phrase or adjective names. That is because a property refers to data, and the name of the property reflects that. PascalCasing is always used for property names.
-*√ DO name properties using a noun, noun phrase, or adjective.
-*X DO NOT have properties that match the name of "Get" methods as in the following example:
-<source lang=csharp enclose=pre>public string TextWriter { get {...} set {...} }
-public string GetTextWriter(int value) { ... } </source>
-This pattern typically indicates that the property should really be a method.
-*√ DO name collection properties with a plural phrase describing the items in the collection instead of using a singular phrase followed by "List" or "Collection."
-*√ DO name Boolean properties with an affirmative phrase (CanSeek instead of CantSeek). Optionally, you can also prefix Boolean properties with "Is," "Can," or "Has," but only where it adds value.
-*√ CONSIDER giving a property the same name as its type.
-For example, the following property correctly gets and sets an enum value named Color, so the property is named Color:
-<source lang=csharp enclose=pre>public enum Color {...}
-public class Control {
-   public Color Color { get {...} set {...} }
-}</source>
-==== Names of Events ====
-Events always refer to some action, either one that is happening or one that has occurred. Therefore, as with methods, events are named with verbs, and verb tense is used to indicate the time when the event is raised.
-*√ DO name events with a verb or a verb phrase.
-Examples include <code>Clicked</code>, <code>Painting</code>, <code>DroppedDown</code>, and so on.
-*√ DO give events names with a concept of before and after, using the present and past tenses.
-For example, a close event that is raised before a window is closed would be called <code>Closing</code>, and one that is raised after the window is closed would be called <code>Closed</code>.
-*X DO NOT use "Before" or "After" prefixes or postfixes to indicate pre- and post-events. Use present and past tenses as just described.
-*√ DO name event handlers (delegates used as types of events) with the "EventHandler" suffix, as shown in the following example: <source lang=csharp enclose=none>public delegate void ClickedEventHandler(object sender, ClickedEventArgs e);</source>
-*√ DO use two parameters named ''sender'' and ''e'' in event handlers.
-The sender parameter represents the object that raised the event. The sender parameter is typically of type <code>object</code>, even if it is possible to employ a more specific type.
-*√ DO name event argument classes with the "EventArgs" suffix.
-==== Names of Fields ====
-The field-naming guidelines apply to static public and protected fields. Internal and private fields are not covered by guidelines, and public or protected instance fields are not allowed by the [http://msdn.microsoft.com/en-us/library/ms229059.aspx member design guidelines].
-*√ DO use PascalCasing in field names.
-*√ DO name fields using a noun, noun phrase, or adjective.
-*X DO NOT use a prefix for field names.
-For example, do not use "g_" or "s_" to indicate static fields.
-=== Names of Parameters ===
-Beyond the obvious reason of readability, it is important to follow the guidelines for parameter names because parameters are displayed in documentation and in the designer when visual design tools provide Intellisense and class browsing functionality.
-*√ DO use camelCasing in parameter names.
-*√ DO use descriptive parameter names.
-*√ CONSIDER using names based on a parameter’s meaning rather than the parameter’s type.
-==== Naming Operator Overload Parameters ====
-*√ DO use ''left'' and ''right'' for binary operator overload parameter names if there is no meaning to the parameters.
-*√ DO use ''value'' for unary operator overload parameter names if there is no meaning to the parameters.
-*√ CONSIDER meaningful names for operator overload parameters if doing so adds significant value.
-*X DO NOT use abbreviations or numeric indices for operator overload parameter names.
-=== Names of Resources ===
-Because localizable resources can be referenced via certain objects as if they were properties, the naming guidelines for resources are similar to property guidelines.
-*√ DO use PascalCasing in resource keys.
-*√ DO provide descriptive rather than short identifiers.
-*X DO NOT use language-specific keywords of the main CLR languages.
-*√ DO use only alphanumeric characters and underscores in naming resources.
-*√ DO use the following naming convention for exception message resources.
-The resource identifier should be the exception type name plus a short identifier of the exception: <code>ArgumentExceptionIllegalCharacters,
-ArgumentExceptionInvalidName,
-ArgumentExceptionFileNameIsMalformed
-</code>.
-== Style Guidelines ==
-=== Tabs and Indenting ===
-*√ DO Tab characters (<code>\0x09</code>) should not be used in code. All indentation should be done with '''4 space characters'''.
-=== Bracing ===
-*√ DO Open braces should always be at the beginning of the line after the statement that begins the block. Contents of the brace should be indented by 4 spaces. For example:
-<source lang=csharp enclose=pre>if (someExpression)
-{
-   DoSomething();
-}
-else
-{
-   DoSomethingElse();
-}
-</source>
-*√ DO “case” statements should be indented from the switch statement like this:
-<source lang=csharp enclose=pre>switch (someExpression)
-{
-   case 0:
-        DoSomething();
-        break;
-   case 1:
-        DoSomethingElse();
-        break;
-   case 2:
-        {
-            int n = 1;
-            DoAnotherThing(n);
-        }
-        break;
-}</source>
-*√ DO NOT Braces should never be considered optional. Even for single statement blocks, you should always use braces. This increases code readability and maintainability. For example:
-<source lang=csharp enclose=pre> for (int i=0; i<100; i++) { DoSomething(i); } </source>
-=== Single Line Statements ===
-*√ DO Single line statements can have braces that begin and end on the same line.
-<source lang=csharp enclose=pre>public class Foo
-{
-   int bar;
-   public int Bar
-   {
-      get { return bar; }
-      set { bar = value; }
-   }
-}
-</source>
-*√ CONSIDER It is suggested that all control structures (if, while, for, etc.) use braces, but it is not required.
-=== Commenting ===
-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.
-==== Documentation Comments ====
-All methods should use XML doc comments. For internal dev comments, the <devdoc> tag should be used.
-<source lang=csharp enclose=pre>public class Foo
-{
-    /// <summary>Public stuff about the method</summary>
-    /// <param name=”bar”>What a neat parameter!</param>
-    /// <devdoc>Cool internal stuff!</devdoc>
-    ///
-    public void MyMethod(int bar) { … }
-}
-</source>
-However, it is common that you would want to move the XML documentation to an external file – for that, use the <code><include></code> tag.
-<source lang=csharp enclose=pre>public class Foo
-{
-   /// <include file='doc\Foo.uex' path='docs/doc[@for="Foo.MyMethod"]/*' />
-   ///
-   public void MyMethod(int bar) { … }
-}
-</source>
-==== Comments Style ====
-The // (two slashes) style of comment tags should be used in most situations. Where ever possible, place comments above the code instead of beside it.  Here are some examples:
-<source lang=csharp enclose=pre>// This is required for WebClient to work through the proxy
-GlobalProxySelection.Select = new WebProxy("http://itgproxy");
-// Create object to access Internet resources//
-WebClient myClient = new WebClient();
-</source>
-Comments can be placed at the end of a line when space allows:
-<source lang=csharp enclose=pre>public class SomethingUseful {
-    private int itemHash;                     // instance member
-    private static bool  hasDoneSomething;    // static member
-}</source>
-=== 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 function arguments.
-**Right: <code>Console.In.Read(myChar, 0, 1);</code>
-**Wrong: <code>Console.In.Read(myChar,0,1);</code>
-*X DO NOT use a space after the parenthesis and function arguments.
-**Right: <code>CreateFoo(myChar, 0, 1);</code>
-**Wrong: <code>CreateFoo( myChar, 0, 1 );</code>
-*X DO NOT use spaces between a function name and parenthesis.
-**Right: <code>CreateFoo();</code>
-**Wrong: <code>CreateFoo ();</code>
-*X DO NOT use spaces inside brackets.
-**Right: <code>x = dataArray[index];</code>
-**Wrong: <code>x = dataArray[ index ];</code>
-*√ DO use a single space before flow control statements.
-**Right: <code>while (x == y)</code>
-**Wrong: <code>while(x==y)</code>
-*√ DO use a single space before and after comparison operators.
-**Right: <code>if (x == y)</code>
-**Wrong: <code>if (x==y)</code>
-== File Organisation ==
-=== Internal Structure ===
-*Source files should contain only one public type, although multiple internal classes are allowed.
-*Source files should be given the name of the public class in the file.
-*Directory names should follow the namespace for the class. For example, I would expect to find the public class <code>System.Windows.Forms.Control</code> in <code>System\Windows\Forms\Control.cs</code>.
-*Classes member should be '''alphabetised''', and grouped into Regions (Fields, Constructors, Properties, Events, Methods, Private interface implementations, Nested types).
-*Using statements should be outside the namespace declaration.
-Example:
-<source lang=csharp enclose=pre>
-using System;
-namespace MyNamespace
-{
-   public class MyClass : IFoo
-   {
-      #region Members
-      int foo;
-      #endregion
-      #region Constructors
-      public MyClass() { … }
-      #endregion
-      #region Properties
-      public int Foo { get { … } set { … } }
-      #endregion
-      #region Events
-      public event EventHandler FooChanged { add { … } remove { … } }
-      #endregion
-      #region Methods
-      void DoSomething() { … }
-      void FindSomethind() { … }
-      #endregion
-      #region Interface Implementations
-      void IFoo.DoSomething() { DoSomething(); }
-      #endregion
-      #region Nested Types
-      class NestedType { … }
-      #endregion
-   }
-}
-</source>
-=== Assembly Structure ===
-'''TODO'''
-</div>