Consistency is the key to maintainable code. This statement is most true for naming your projects, source files, and
identifiers including Fields, Variables, Properties, Methods, Parameters, Classes, Interfaces, and Namespaces.
General Guidelines
1. Always use Camel Case or Pascal Case names.
2. Avoid ALL CAPS and all lowercase names. Single lowercase words or letters are acceptable.
3. Do not create declarations of the same type (namespace, class, method, property, field, or parameter) and
access modifier (protected, public, private, internal) that vary only by capitalization.
4. Do not use names that begin with a numeric character.
5. Do add numeric suffixes to identifier names.
6. Always choose meaningful and specific names.
7. Always err on the side of verbosity not terseness.
8. Variables and Properties should describe an entity not the type or size.
9. Do not use Hungarian Notation!
Example: strName or iCount
10. Avoid using abbreviations unless the full name is excessive.
11. Avoid abbreviations longer than 5 characters.
12. Any Abbreviations must be widely known and accepted.
13. Use uppercase for two-letter abbreviations, and Pascal Case for longer abbreviations.
14. Do not use C# reserved words as names.
15. Avoid naming conflicts with existing .NET Framework namespaces, or types.
16. Avoid adding redundant or meaningless prefixes and suffixes to identifiers
Example:
// Bad!
public enum ColorsEnum {…}
public class CVehicle {…}
public struct RectangleStruct {…}
17. Do not include the parent class name within a property name.
Example: Customer.Name NOT Customer.CustomerName
18. Try to prefix Boolean variables and properties with “Can”, “Is” or “Has”.
19. Append computational qualifiers to variable names like Average, Count, Sum, Min, and Max where
appropriate.
20. When defining a root namespace, use a Product, Company, or Developer Name as the root. Example:
LanceHunt.StringUtilities
Coding Style
Coding style causes the most inconsistency and controversy between developers. Each developer has a preference, and
rarely are two the same. However, consistent layout, format, and organization are key to creating maintainable code.
The following sections describe the preferred way to implement C# source code in order to create readable, clear, and
consistent code that is easy to understand and maintain.
3.1 Formatting
1. Never declare more than 1 namespace per file.
2. Avoid putting multiple classes in a single file.
3. Always place curly braces ({ and }) on a new line.
4. Always use curly braces ({ and }) in conditional statements.
5. Always use a Tab & Indention size of 4.
6. Declare each variable independently – not in the same statement.
7. Place namespace “using” statements together at the top of file. Group .NET namespaces above custom
namespaces.
8. Group internal class implementation by type in the following order:
a. Member variables.
b. Constructors & Finalizers.
c. Nested Enums, Structs, and Classes.
d. Properties
e. Methods
9. Sequence declarations within type groups based upon access modifier and visibility:
a. Public
b. Protected
c. Internal
d. Private
10. Segregate interface Implementation by using #region statements.
11. Append folder-name to namespace for source files within sub-folders.
12. Recursively indent all code blocks contained within braces.
13. Use white space (CR/LF, Tabs, etc) liberally to separate and organize code.
14. Only declare related attribute declarations on a single line, otherwise stack each attribute as a separate
declaration.
Example:
// Bad!
[Attrbute1, Attrbute2, Attrbute3]
public class MyClass
{…}
// Good!
[Attrbute1, RelatedAttribute2]
[Attrbute3]
[Attrbute4]
public class MyClass
{…}
15. Place Assembly scope attribute declarations on a separate line.
16. Place Type scope attribute declarations on a separate line.
17. Place Method scope attribute declarations on a separate line.
18. Place Member scope attribute declarations on a separate line.
19. Place Parameter attribute declarations inline with the parameter.
20. If in doubt, always err on the side of clarity and consistency.
Code Commenting
21. All comments should be written in the same language, be grammatically correct, and contain appropriate
punctuation.
22. Use // or /// but never /* … */
23. Do not “flowerbox” comment blocks.
Example:
// ***************************************
// Comment block
// ***************************************
24. Use inline-comments to explain assumptions, known issues, and algorithm insights.
25. Do not use inline-comments to explain obvious code. Well written code is self documenting.
26. Only use comments for bad code to say “fix this code” – otherwise remove, or rewrite the code!
27. Include comments using Task-List keyword flags to allow comment-filtering.
Example:
// TODO: Place Database Code Here
// UNDONE: Removed P\Invoke Call due to errors
// HACK: Temporary fix until able to refactor
28. Always apply C# comment-blocks (///) to public, protected, and internal declarations.
29. Only use C# comment-blocks for documenting the API.
30. Always include comments. Include , , and comment
sections where applicable.
31. Include and where possible.
32. Always add CDATA tags to comments containing code and other embedded markup in order to avoid
encoding issues.
Example:
///
/// Add the following key to the “appSettings” section of your config:
///
///
///
///
///
/// ]]>
///
|
Views : 696
Rating : Excellent
Posted : 03 Apr 2009
Publisher : GurunathanM
|