Difference between revisions of "Front-End Standard"

From SmartHCM Wiki
Jump to navigation Jump to search
Line 1,136: Line 1,136:
  
 
Use Single-Line formatting. This is the most space and size efficient way to write CSS:
 
Use Single-Line formatting. This is the most space and size efficient way to write CSS:
Example:
+
'''Example:'''
  
 
div.wrapper { margin:0 auto; padding:200px 0 0 0; width:960px; z-index:2 }  
 
div.wrapper { margin:0 auto; padding:200px 0 0 0; width:960px; z-index:2 }  

Revision as of 09:28, 30 April 2015


Contents

Introduction

This document describes rules and recommendations for developing applications in .NET and class libraries using the C# Language. The goal is to define guidelines to enforce consistent style and formatting and help developers avoid common pitfalls and mistakes.

This document covers Naming Conventions, Coding Style, Language Usage, Object Model Design and Tips for developers.

Document Convention

Much like the ensuing coding standards, this document requires standards in order to ensure clarity when stating the rules and guidelines. Certain conventions are used throughout this document to add emphasis.

Below are some of the common conventions used throughout this document.

Coloring & Emphasis

Blue: Text colored blue indicates a keyword or .NET type.

Bold: Text with additional emphasis to make it stand-out.

Keywords

Always: Emphasizes this rule must be enforced.

Never: Emphasizes this action must not happen.

Do Not: Emphasizes this action must not happen.

Avoid: Emphasizes that the action should be prevented, but some exceptions may exist.

Try: Emphasizes that the rule should be attempted whenever possible and appropriate.

Example:Precedes text used to illustrate a rule or recommendation.

Reason: Explains the thoughts and purpose behind a rule or recommendation.


Terminology & Definitions

The following terminology is referenced throughout this document:

Access Modifier

C# keywords public, protected, internal, and private declare the allowed code-accessibility of types and their members. Although default access modifiers vary, classes and most other members use the default of private. Notable exceptions are interfaces and enums which both default to public.

Camel Case

A word with the first letter lowercase, and the first letter of each subsequent word-part capitalized.

Example: customerName

Common Type System

The .NET Framework common type system (CTS) defines how types are declared, used, and managed. All native C# types are based upon the CTS to ensure support for cross-language integration.

Identifier

A developer defined token used to uniquely name a declared object or object instance.

Example: public class MyClassNameIdentifier { … }

Pascal Case

A word with the first letter capitalized, and the first letter of each subsequent word-part capitalized.

Example: CustomerName

Premature Generalization

As it applies to object model design; this is the act of creating abstractions within an object model not based upon concrete requirements or a known future need for the abstraction. In simplest terms: “Abstraction for the sake of Abstraction.”

Flags

The following flags are used to help clarify or categorize certain statements:

Quick Summary This section contains tables describing a high-level summary of the major standards covered in this document. These tables are not comprehensive, but give a quick glance at commonly referenced elements.

Naming Conventions

  • “c” = camelCase
  • “P” = PascalCase
  • “_” = Prefix with _Underscore
  • “x” = Not Applicable.
Identifier Public Protected Internal Private Notes
Project File P x x x Match Assembly & Namespace.
Source File P x x x Match contained class.
Other Files P x x x Apply where possible.
Namespace P x x x Partial Project/Assembly match.
Class or Struct P P P P Add suffix of subclass.
Interface P P P P Prefix with a capital I.
Source FileGeneric Class P P P P Use T or K as Type identifier.
Method P P P P Use a Verb or Verb-Object pair
Property P P P P Do not prefix with Get or Set.
Field P P v _c Only use Private fields.No Hungarian Notation!
Constant P P P _c
Static Field P P P _c Only use Private fields.
Enum P P P P Options are also Pascal Case.
Delegate P P P P
Event P x x x
Inline Variable x x x c Avoid single-character and enumerated names.
Parameter P x x c

Coding Style

Code Style
Source Files One Namespace per file and one class per file.
Curly Braces On new line. Always use braces when optional.
Indention Use tabs with size of 4.
Comments Use // or /// but not /* … */ and do not flowerbox.
Variables One variable per declaration.

Language Usage

Code Style
Native Data Types Use built-in C# native data types vs .NET CTS types. (Use int NOT Int32)
Enums Avoid changing default type.
Generics Prefer Generic Types over standard or strong-typed classes.
Properties Never prefix with Get or Set.
Methods Use a maximum of 7 parameters.
base and this Use only in constructors or within an override.
Ternary conditions Avoid complex conditions.
for each statements Do not modify enumerated items within a foreach statement.
Conditionals Avoid evaluating Boolean conditions against true or false.No embedded assignment.Avoid embedded method invocation.
Exceptions Do not use exceptions for flow control.Use throw; not throw e; when re-throwing.Only catch what you can handle.Use validation to avoid exceptions.Derive from Execption not ApplicationException.
Events Always check for null before invoking.
Locking Use lock() not Monitor.Enter().Do not lock on an object type or “this”.Do lock on private objects.
Dispose() & Close() Always invoke them if offered, declare where needed.
Finalizers Avoid.Use the C# Destructors.Do not create Finalize() method.
Assembly Version Increment manually.
ComVisibleAttribute Set to false for all assemblies

Naming Conventions

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

  • Always use Camel Case or Pascal Case names.
  • Avoid ALL CAPS and all lowercase names. Single lowercase words or letters are acceptable.
  • 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.
  • Do not use names that begin with a numeric character.
  • Do add numeric suffixes to identifier names.
  • Always choose meaningful and specific names.
  • Variables and Properties should describe an entity not the type or size.
  • Do not use Hungarian Notation!

Example: strName or iCount

  • Avoid using abbreviations unless the full name is excessive.
  • Avoid abbreviations longer than 5 characters.
  • Any Abbreviations must be widely known and accepted.
  • Use uppercase for two-letter abbreviations, and Pascal Case for longer abbreviations.
  • Do not use C# reserved words as names.
  • Avoid naming conflicts with existing .NET Framework namespaces, or types.
  • Avoid adding redundant or meaningless prefixes and suffixes to identifiers

Example: // Bad! public enum ColorsEnum {…} public class CVehicle {…} public struct RectangleStruct {…}

  • Do not include the parent class name within a property name.

Example: Customer.Name NOT Customer.CustomerName

  • Try to prefix Boolean variables and properties with “Can”, “Is” or “Has”.
  • Append computational qualifiers to variable names like Average, Count, Sum, Min, and Max where appropriate.
  • When defining a root namespace, use a Product, Company, or Developer Name as the root. Example: SmartHCM.StringUtilities
Identifier Naming Convention
Project File Pascal Case.Always match Assembly Name & Root Namespace.Example:SmartHCM.Web.csproj -> SmartHCM.Web.dll -> namespace

SmartHCM.Web

Source File Pascal Case.Always match Class name and file name.Avoid including more than one Class, Enum (global), or Delegate (global) per file. Use a descriptive file name when containing multiple Class, Enum, or Delegates.Example:MyClass.cs => public class MyClass{…}
ResourceorEmbedded File Try to use Pascal Case.Use a name describing the file contents.
Namespace Pascal Case.Try to partially match Project/Assembly Name.Example:namespace SmartHCM.Web{…}
Class or Struct Pascal Case.Use a noun or noun phrase for class name.Add an appropriate class-suffix when sub-classing another type when possible.Examples:

private class MyClass {…}internal class SpecializedAttribute : Attribute {…}public class CustomerCollection : CollectionBase {…}

public class CustomEventArgs : EventArgs {…}private struct ApplicationSettings{…}
Interface Pascal Case.Always prefix interface name with capital “I”.Example:interface ICustomer{…}
Generic Class & Generic Parameter Type Always use a single capital letter, such as T or K.Example:public class FifoStack<T>{public void Push(<T> obj){…}public <T> Pop(){…}}
Method Pascal Case.Try to use a Verb or Verb-Object pair.Example:public void Execute() {…}private string GetAssemblyVersion(Assembly target) {…}
Property Pascal Case.Property name should represent the entity it returns. Never prefix property names with“Get” or “Set”.Example:public string Name{get{…}set{…}}
Field(Public, Protected,or Internal) Pascal Case.Avoid using non-private Fields!Use Properties instead.Example:public string Name;protected IList InnerList;
Field (Private) Camel Case and prefix with a single underscore (_) character.Example:private string _name;
Constant orStatic Field Treat like a Field.Choose appropriate Field access-modifier above.
Enum Pascal Case (both the Type and the Options).Add the FlagsAttribute to bit-mask multiple options.Example:public enum CustomerTypes{Consumer,Commercial}
Delegate or Event Treat as a Field.Choose appropriate Field access-modifier above.
Example:public event EventHandler LoadPlugin;
Variable (inline) Camel Case.Avoid using single characters like “x” or “y” except in FOR loops.Avoid enumerating variable names like text1, text2, text3 etc.
Parameter Camel Case.Example:public void Execute(string commandText, int iterations){…}

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 source code in order to create readable, clear, and consistent code that is easy to understand and maintain.

Formatting

  • Never declare more than 1 namespace per file.
  • Avoid putting multiple classes in a single file.
  • Always place curly braces ({ and }) on a new line.
  • Curly braces ( {} ) should be in the same level as the code outside the braces.

Example: if ( … ) { // Do something! // … return false; }

  • Always use curly braces ({ and }) in conditional statements.
  • Always use a Tab & Indention size of 4.
  • Use one blank line to separate logical groups of code.
  • There should be one and only one single blank line between each method inside the class.
  • Declare each variable independently – not in the same statement.
  • Place namespace “using” statements together at the top of file. Group .NET namespaces above custom namespaces.
  • 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

  • Sequence declarations within type groups based upon access modifier and visibility:

a.Public b.Protected c.Internal d.Private

  • Segregate interface Implementation by using #region statements.
  • Use #region to group related pieces of code together. If you use proper grouping using #region, the page should like this when all definitions are collapsed.

Example:

  • Recursively indent all code blocks contained within braces.
  • Use white space (CR/LF, Tabs, etc) liberally to separate and organize code.

Code Commenting

  • All comments should be written in the same language, be grammatically correct, and contain appropriate punctuation.
  • Use // or /// but never /* … */
  • Do not “flowerbox” comment blocks.

Example: // *************************************** // Comment block // ***************************************

  • Use inline-comments to explain assumptions, known issues, and algorithm insights.
  • Do not use inline-comments to explain obvious code. Well written code is self documenting.
  • Only use comments for bad code to say “fix this code” – otherwise remove, or rewrite the code!
  • 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

  • Always apply C# comment-blocks (///) to public, protected, and internal declarations.
  • Only use C# comment-blocks for documenting the API.
  • Always include <summary> comments. Include <param>, <return>, and <exception> comment sections where applicable.
  • Include <see cref=””/> and <seeAlso cref=””/> where possible.
  • Always add CDATA tags to comments containing code and other embedded markup in order to avoid encoding issues.

Example: /// <example> /// Add the following key to the “appSettings” section of your config: /// <![CDATA[ /// <configuration> /// <appSettings> /// <add key=”mySetting” value=”myValue”/> /// </appSettings> /// </configuration> /// ]]> /// </example>

Language Usage

General

  • Do not omit access modifiers. Explicitly declare all identifiers with the appropriate access modifier instead of allowing the default.

Example: // Bad! void WriteEvent(string message) {…} // Good! private void WriteEvent(string message) {…}

  • Do not use the default (“1.0.*”) versioning scheme. Increment the AssemblyVersionAttribute value manually.
  • Set the ComVisibleAttribute to false for all assemblies.
  • Only selectively enable the ComVisibleAttribute for individual classes when needed.

Example: [assembly: ComVisible(false)] [ComVisible(true)] public MyClass {…}

  • Consider factoring classes containing unsafe code blocks into a separate assembly.
  • Avoid mutual references between assemblies.
  • Use enum wherever required. Do not use numbers or strings to indicate discrete values.

Example: // Bad!

SmartHCM Installation 15-..png


// Good!


SmartHCM Installation 17.png

Variables & Types

  • Try to initialize variables where you declare them.
  • Always choose the simplest data type, list, or object required.
  • Always use the built-in C# data type aliases, not the .NET common type system (CTS).

Example: short NOT System.Int16 int NOT System.Int32 long NOT System.Int64 string NOT System.String

  • Only declare member variables as private. Use properties to provide access to them with public, protected, or internal access modifiers.
  • Try to use int for any non-fractional numeric values that will fit the int datatype - even variables for nonnegative numbers.
  • Only use long for variables potentially containing values too large for an int.
  • Try to use double for fractional numbers to ensure decimal precision in calculations.
  • Only use float for fractional numbers that will not fit double or decimal.
  • Avoid using float unless you fully understand the implications upon any calculations.
  • Try to use decimal when fractional numbers must be rounded to a fixed precision for calculations. Typically this will involve money.
  • Avoid using sbyte, short, uint, and ulong unless it is for interop (P/Invoke) with native libraries.
  • Avoid specifying the type for an enum - use the default of int unless you have an explicit need for long (very uncommon).
  • Avoid using inline numeric literals (magic numbers). Instead, use a Constant or Enum.
  • Avoid declaring string literals inline. Instead use Resources, Constants and Configuration Files, Registry or other data sources.
  • Declare readonly or static readonly variables instead of constants for complex types.
  • Only declare constants for simple types.
  • Avoid direct casts. Instead, use the “as” operator and check for null.

Example: object dataObject = LoadData(); DataSet ds = dataObject as DataSet; if(ds != null) {…}

  • Always prefer C# Generic collection types over standard or strong-typed collections.
  • Always explicitly initialize arrays of reference types using a for loop.
  • Avoid boxing and unboxing value types.

Example: int count = 1; object refCount = count; // Implicitly boxed. int newCount = (int)refCount; // Explicitly unboxed.

  • Floating point values should include at least one digit before the decimal place and one after.

Example: totalPercent = 0.05.

  • Try to use the “@” prefix for string literals instead of escaped strings.
  • Prefer String.Format() or StringBuilder over string concatenation.
  • Never concatenate strings inside a loop.
  • Do not compare strings to String.Empty or “” to check for empty strings. Instead, compare by using String.Length == 0.
  • Avoid hidden string allocations within a loop. Use String.Compare() for case-sensitive

Example: (ToLower() creates a temp string) // Bad! int id = -1; string name = “lance hunt”; for(int i=0; i < customerList.Count; i++) { if(customerList[i].Name.ToLower() == name) { id = customerList[i].ID; } } // Good! int id = -1; string name = “lance hunt”; for(int i=0; i < customerList.Count; i++) { // The “ignoreCase = true” argument performs a // case-insensitive compare without new allocation. if(String.Compare(customerList[i].Name, name, true)== 0) { id = customerList[i].ID; } }

Flow Control

  • Avoid invoking methods within a conditional expression.
  • Avoid creating recursive methods. Use loops or nested loops instead.
  • Avoid using foreach to iterate over immutable value-type collections. E.g. String arrays.
  • Do not modify enumerated items within a foreach statement.
  • Use the ternary conditional operator only for trivial conditions. Avoid complex or compound ternary operations.

Example: int result = isValid ? 9 : 4;

  • Avoid evaluating Boolean conditions against true or false.

Example: // Bad! if (isValid == true) {…} // Good! if (isValid) {…}

  • Avoid assignment within conditional statements.

Example: if((i=2)==2) {…}

  • Avoid compound conditional expressions – use Boolean variables to split parts into multiple manageable expressions.

Example: // Bad! if (((value > _highScore) && (value != _highScore)) && (value < _maxScore)) {…} // Good! isHighScore = (value >= _highScore); isTiedHigh = (value == _highScore); isValid = (value < _maxValue); if ((isHighScore && ! isTiedHigh) && isValid) {…}

  • Avoid explicit Boolean tests in conditionals.

Example: // Bad! if(IsValid == true) {…}; // Good! if(IsValid) {…}

  • Only use switch/case statements for simple operations with parallel conditional logic.
  • Prefer nested if/else over switch/case for short conditional sequences and complex conditions.
  • Prefer polymorphism over switch/case to encapsulate and delegate complex operations.

Exceptions

  • Do not use try/catch blocks for flow-control.
  • Only catch exceptions that you can handle.
  • Never declare an empty catch block.
  • Avoid nesting a try/catch within a catch block.
  • Always catch the most derived exception via exception filters.
  • Order exception filters from most to least derived exception type.
  • Avoid re-throwing an exception. Allow it to bubble-up instead.
  • If re-throwing an exception, preserve the original call stack by omitting the exception argument from the throw statement.

Example: // Bad! catch(Exception ex) { Log(ex); throw ex; } // Good! catch(Exception) { Log(ex); throw; }

  • Only use the finally block to release resources from a try statement.
  • Always use validation to avoid exceptions.

Example: // Bad! try { conn.Close(); } Catch(Exception ex) // handle exception if already closed! } // Good! if(conn.State != ConnectionState.Closed) { conn.Close(); }

  • Always set the innerException property on thrown exceptions so the exception chain & call stack are maintained.
  • Avoid defining custom exception classes. Use existing exception classes instead.

Events, Delegates, & Threading

  • Always check Event & Delegate instances for null before invoking.
  • Use the default EventHandler and EventArgs for most simple events.
  • Always derive a custom EventArgs class to provide additional data.
  • Use the existing CancelEventArgs class to allow the event subscriber to control events.
  • Always use the “lock” keyword instead of the Monitor type.
  • Only lock on a private or private static object.

Example: lock(myVariable);

  • Avoid locking on a Type.

Example: lock(typeof(MyClass));

  • Avoid locking on the current object instance.

Example: lock(this);

Object Composition

  • Always declare types explicitly within a namespace. Do not use the default “{global}” namespace.
  • Avoid overuse of the public access modifier. Typically fewer than 10% of your types and members will be part of a public API, unless you are writing a class library.
  • Consider using internal or private access modifiers for types and members unless you intend to support them as part of a public API.
  • Never use the protected access modifier within sealed classes unless overriding a protected member of an inherited type.

Avoid declaring methods with more than 5 parameters. Consider refactoring this code.

  • Try to replace large parameter sets (more than 5 parameters) with one or more class or struct parameters especially when used in multiple method signatures.
  • Do not use the “new” keyword on method and property declarations.
  • Only use the “base” keyword when invoking a base class constructor or base implementation within an override.
  • Always validate an enumeration variable or parameter value before consuming it. They may contain any value that the underlying Enum type (default int) supports.

Example: public void Test(BookCategory cat) { if (Enum.IsDefined(typeof(BookCategory), cat)) {…} }

  • Consider overriding Equals() on a struct.
  • Always override the Equality Operator (==) when overriding the Equals() method.
  • Always override the String Implicit Operator when overriding the ToString() method.
  • Always call Close() or Dispose() on classes that offer it.
  • Wrap instantiation of IDisposable objects with a “using” statement to ensure that Dispose() is automatically called.

Example: using(SqlConnection cn = new SqlConnection(_connectionString)) {…}

  • Always implement the IDisposable interface & pattern on classes referencing external resources.

Example: public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } protected virtual void Dispose(bool disposing) { if (disposing) { // Free other state (managed objects). } // Free your own state (unmanaged objects). // Set large fields to null. }

Object Model & API Design

  • Always prefer aggregation over inheritance.
  • Avoid “Premature Generalization”. Create abstractions only when the intent is understood.
  • Do the simplest thing that works, then refactor when necessary.
  • Always make object-behavior transparent to API consumers.
  • Avoid unexpected side-affects when properties, methods, and constructors are invoked.
  • Always separate presentation layer from business logic.
  • Always prefer interfaces over abstract classes.
  • Try to include the design-pattern names such as “Bridge”, “Adapter”, or “Factory” as a suffix to class names where appropriate.
  • Only make members virtual if they are designed and tested for extensibility.

8Refactor often!

  • Separate your application into multiple assemblies. Group all independent utility classes into a separate class library. All your database related files can be in another class library.

JavaScript Standards

This is a set of coding conventions and rules for use in JavaScript programming. All of our JavaScript code is sent directly to the public. It should always be of publication quality.

JavaScript features

Make sure that your code doesn't generate any strict JavaScript warnings, such as: •Duplicate variable declaration •Mixing return; with return value; •Trailing comma in JavaScript object declarations •Undeclared variables or members. •Don't compare booleans to true or false. For example, write if (ioService.offline). Compare objects to null, numbers to 0 or strings to "".

JavaScript Files

JavaScript programs should be stored in and delivered as .js files. JavaScript code should not be embedded in HTML files unless the code is specific to a single session. Code in HTML adds significantly to pageweight with no opportunity for mitigation by caching and compression. <script src=filename.js> tags should be placed as late in the body as possible. This reduces the effects of delays imposed by script loading on other page components.

Spaces, Linebreaks and Indentation

•Use two spaces for indentation. Don't use literal tab characters. •Put a space after control keywords like if and for. •Don't put spaces after function names. •Put a space after commas in argument lists. •The use of spaces can produce a larger filesize, but the size is not significant over local networks, and the difference is eliminated by minification.

Line Length

•Avoid lines longer than 70 characters. •When a statement will not fit on a single line, it may be necessary to break it. •Place the break after an operator, ideally after a comma. •The next line should be indented 8 spaces.

Comments

•Be generous with comments. •Strongly prefer // comments for making comments inside the bodies of functions and methods (this lets someone easily comment out a block of code while debugging later). •It is useful to leave information that will be read at a later time by people (possibly yourself) who will need to understand what you have done. •The comments should be well-written and clear. •It is important that comments be kept up-to-date. •Make comments meaningful. •Focus on what is not immediately visible. Don't waste the reader's time with stuff like oi = 0; // Set i to zero. •Generally use line comments. Save block comments for formal documentation.

Variable Declarations

•All variables should be declared before used. JavaScript does not require this, but doing so makes the program easier to read and makes it easier to detect undeclared variables. •The var statement should be the first statement in the function body. •It is preferred that each variable be given its own line and comment. Example: var currentEntry, // currently selected table entry level, // indentation level size; // size of table

Function Declarations

•All functions should be declared before they are used. •The function keyword must be followed by one space. •Inner functions should follow the var statement. This helps make it clear what variables are included in its scope. •There should be no space between the name of a function and the left parenthesis of its parameter list. •There should be one space between the right parenthesis and the left curly brace that begins the statement body. •The body itself is indented four spaces. •The right curly brace is aligned with the line containing the beginning of the declaration of the function. Example: function outer(c, d) { var e = c * d;

function inner(a, b) { return (e * a) + b; }

return inner(0, 1); }

Function Calls

•Functions should be called with no spaces between the function name, the opening parenthesis, and the first parameter. •There should be one space between commas and each parameter, and there should not be a space between the last parameter, the closing parenthesis, and the semicolon. Example: var foobar = foo(bar, baz, quux); •There should be one space on either side of an equals sign used to assign the return value of a function to a variable.

Names, Case and Capitalization

•Names should be formed from the 26 upper and lower case letters, 10 digits and underscore. •Name methods and properties using camelCase. •Name global functions using camelCase. Avoid defining global functions. •Name constants using UPPERCASE. •Do not use $ (dollar sign) or \ (backslash) in names. •Do not use underscore as the first or last character of a name. It is sometimes intended to indicate privacy, but it does not actually provide privacy. •Variables and functions must use camelCase. In case a variable contains a jQuery object, the variable MUST start with a dollar sign ($): •Constructor functions that must be used with the new prefix should start with a capital letter. •Write true, false, and null in lowercase. •Global variables should be in all caps.

Statements

•Each line should contain at most one statement. •Put semicolon at the end of every simple statement. •All statements (except for, function, if, switch, try, while) MUST be followed by a semicolon. •JavaScript allows any expression to be used as a statement. The only expressions that should be used as statements are assignments. •A return statement with a value should not use parentheses around the value. •The return value expression must start on the same line as the return keyword. •Avoid use of the continue statement. It tends to obscure the control flow of the function.

Whitespace

•Blank lines improve readability by setting off sections of code that are logically related. •All code must not end with trailing whitespace. •A keyword followed by left parenthesis should be separated by a space. Example: while (true) {

Confusing Pluses and Minuses

Be careful to not follow a + with + or ++. This pattern can be confusing. Insert parenthesis between them to make your intention clear. Example: // Bad total = subtotal + +myInput.value; // Good total = subtotal + (+myInput.value);

ASP.NET Coding Standards

We will explore best practices in ASP.NET development in this section.

Choose pattern correctly

Choosing the correct pattern for your application development is a must.

It's not always that 3-Tier, MVC, MVP or MVVM is best; if you have a fixed small size system which is not going to be extended in the future then 1-Tier/2-Tier will be good.

DataTier

Always follow some guidelines for SQL queries.

•Never access database from the UI pages. Always have a data layer class which performs all the database related tasks. This will help you support or migrate to another database back end easily. •Separate your application into multiple assemblies. Group all independent utility classes into a separate class library. All your database related files can be in another class library. •Alias names like a,b,emp make queries unreadable and query management becomes very difficult. Use meaningful and proper alias names for tables. Example: TblEmployee Manager OR TblEmployee Developer. •If more than a single developer will work on a project then always put a description at the top of every procedure along with the creator name. •If in a query, in a where condition if a column with a primary key/unique key is involved, there is no need to put other conditions. Example: Select * FROM TblEmployee WHERE EmploeyeeId=@EmployeeId AND AccountId=@AccountId

App_Offline.htm file

Many people are unaware of this file. When you add a htm file name such as app_offline, every ASP.NET request will be redirected to this page. Use this page when you want to take your website offline temporarily, instead of writing your own logic for it.

Validation Controls

Use ASP.NET validation controls for validation because it supports both client side and server side validation.

Page.IsValid

Always check for this property value in Control events like Button_click when validation is being done using Validation Controls because it's easy to bypass JavaScript code.

Control State

While developing user controls if maintaining state is a must then use control states instead of viewstate.

Naming Convention

Always follow a consistent Naming Guidelines and standards, which should include everything. Use appropriate prefix for each of the UI element. A brief list is given below. Since .NET has given several controls, you may have to arrive at a complete list of standard prefixes for each of the controls (including third party controls) you are using.

Control Prefix
Label lbl
TextBox txt
DataGrid dg
Button btn
ImageButton imgbtn
Hyperlink hlk
DropDownList ddl
ListBox isb
DataList dl
Repeater rpt
Checkbox cb
CheckboxList cbl
RadioButton rb
RadioButtonList rbl
Image img
Panel pnl
PlaceHolder ph
Table tbl tbl
Validators val
Grid Panel gp

CSS and JS

Never use inline or internal CSS, go with an external. The same applies to JS. (When we include external css/js in the page it is cached and so wont download on every request.)

Master Pages

Always use Master pages for consistent layout instead of frames and iframes. Although Master Pages seem like a parent they are actually a child or in short we can say they behave like a user control for pages.

Session

•Always encapsulate session values. •Do not store large objects in session. Storing large objects in session may consume lot of server memory depending on the number of users. •Do not use session variables throughout the code. Use session variables only within the classes and expose methods to access the value stored in the session variables. A class can access the session using System.Web.HttpCOntext.Current.Session

ASP.NET life cycle

•Every ASP.NET developer must properly understand the various events exposed during the page life cycle. Each event has it s own significance and use; see:

Life Cycle Events

•PreInit •Init •LoadViewState(Fires only if IsPostBack is true) •LoadPostData(Fires only if IsPostBack is true) •PreLoad •Load •Control events(Fires only if IsPostBack is true) •PreRender •SaveViewState •Render •Unload

File Naming and Organization

The following example file structure should be used for static resources (framework-specific conventions take precedence): /css /reset.css /main.css /ie.css /img /btn-submit.png /btn-submit-SOURCE.psd /es /btn-submit.png /media /js /files

HTML Coding Standards

We will explore best practices in HTML coding standards in this section.

HTML General Rules

•Always close your tags; •IDs and classes should contain lowercase letters and words should be separated with a hyphen. Example:

•Use clear and precise names for IDs and classes. •Choose names according to semantic meaning rather than presentation. •Avoid using unnecessary classes and wrapper elements. •Remove trailing white spaces. •Use actual P elements for paragraph delimiters as opposed to multiple BR tags. •Break up lines when they run too long. It is much easier to read and understand code when you can see the entire line at once. •Keep your tag names lowercase: 'Example:'Bold text // Bad

Bad Example.

// Good

Good Example.

•Use H1 – H6 tags. For semantic and SEO reasons, try to use heading tags. The hierarchy of them in the page is important too. •Wrap navigation with an unordered list; Example:

  • <a href>=”#”>Home</a>
  • <a href=”#”>About</a>
  • <a href=”#”>Contact</a>

• Always complete the alt attribute of an image. • For naming ID's of HTML tags, use Camel Case and for naming classes use lower case: Example:

  • <a href>=”#”>Home</a>
  • <a href=”#”>About</a>
  • <a href=”#”>Contact</a>

12.2 HTML Markup Formatting • Place a comment tag at the end of each important HTML container that notifies the end of that specific tag; Example:

<form action="" method="post"> <input type="text" name="username" class="login-username" value="Please type your email address"/>
<input type="password" name="password" class="login-password" value="Please type your password"/>
<input type="submit" value="" class="login-button" />
</form>

•When you want to add comments inside ASP.NET Web Controls, use this syntax: Example: <%-- ASP.NET syntax for comments --%> •Use one blank line to separate important HTML containers; Example:

•Use TAB for indentation. Do not use spaces. Recommended TAB size is 4; •Use a new line for every block, list, or table element, and indent every such child element. •When quoting attributes values, use double quotation marks.

CSS Coding Standards

We will explore best practices in CSS coding standards in this section.

Stylesheet Organization

We will explore stylesheet organization in this section.

Document Head

/****************************************************************************

Color Reference: red: #FF0000 blue: #0000FF gray: #333333

                                                                                                                                                        • /

Each main stylesheet should contain a document head.

Optionally, the document head may contain a color reference. A color reference is an index of colors commonly used in the design. This reference makes it easy to identify specific color values without a color picker. It is also useful when a color is updated, since a quick find/replace can be completed.

A description, table of contents, or other meta data may be included in this head as deemed appropriate.

Sections

CSS style blocks should be grouped by section and ordered according to the markup in the HTML document. Common sections include the following: •Global •Type •Forms •Header •Navigation •Content •Footer Page or layout specific sections may be added. Sections should be denoted with comments which use the following format: /* ************************************

  • @Section: Global
                                                                          • */

Two empty lines should precede each section comment. The '@' symbol is used to quickly traverse the stylesheet using a text editor's "Find Next" feature.

CSS General Rules

•Use margin: 0px auto; as a CSS attribute for centering a div inside container; •Use .px as measurement unit in design. It’s easier to control than .em and all the developers on a project can understand it; •Use CSS reset class, example: *{margin: 0px; padding: 0px}. You can add additional attributes to this class depending on your requirements. •Use structural naming convention instead of a presentational naming convention: Example: // Bad

Bad Example <a href="#" class="red-link">presentational convention</a>

// Good

Good Example <a href="#" class="article-link">structural convention</a>

CSS Formatting

Each style block should adhere to the following format: Example: selector { property: value; }

selector-2 { property: value; property: value; }

Use Single-Line formatting. This is the most space and size efficient way to write CSS: Example:

div.wrapper { margin:0 auto; padding:200px 0 0 0; width:960px; z-index:2 } ul.nav { position:absolute; top:0; left:430px; padding:120px 0 0 0 } ul.nav li { display:inline; margin:0 10px 0 0 } div.column { float:left; margin:0 70px 0 0; padding:0 0 0 70px; width:340px } div.post-wrapper { bottom center no-repeat; margin:0 0 40px 0; padding:0 0 40px 0 } div.wrapper img, div.wrapper a img, div.article_illustration_mini { background:#d3d4cb; padding:10px; border:1px solid #999 } div.wrapper a:hover img { background:#fff }

Use one blank line to separate logical groups of styling:

Example: table thead tr th.left-corner { /* CSS style */ } table thead tr th.right-corner { /* CSS style */ }

table#AddNewUser{ /* CSS style */ } table#AddNewUser thead tr th h3{ /* CSS style */ }

Order your CSS properties. For example, if you are styling a

tag, put first the font-related declarations then color-related declarations and finally the position-related declarations: Example: h1 { /* Font */ font-size: 2em; font-weight: bold; /* Color */ color: #c00; background: #fff; /* Box model */ padding: 10px; margin-bottom: 1em; } Comments are optional, so is the formatting. Order the CSS items in groups. This way you can easily read the contents and jump straight to a particular section. Pretending each heading with a dollar sign makes it unique, so that a search will yield only headings: Example: /*$DEFAULTS

body { background: #b6b7bc; font-size: .80em; font-family: "Helvetica Neue", "Lucida Grande", "Segoe UI", Arial, Helvetica, Verdana, sans-serif; margin: 0px; padding: 0px; color: #696969;} a:link, a:visited{ color: #034af3;} a:hover{ color: #1d60ff; text-decoration: none;} a:active{ color: #034af3;} p{ margin-bottom: 10px; line-height: 1.6em;} /* $HEADINGS


*/

h1, h2, h3, h4, h5, h6{ font-size: 1.5em; color: #666666; font-variant: small-caps; text-transform: none; font-weight: 400; margin-bottom: 0px;} h1{ font-size: 1.6em; padding-bottom: 0px; margin-bottom: 0px;} h2{ font-size: 1.5em; font-weight: 600;} h3{ font-size: 1.2em;} h4{ font-size: 1.1em;} h5, h6{ font-size: 1em;}

Best Programming Guidelines

  • Make sure that there shouldn't be any project warnings.
  • All unused usings need to be removed. Code cleanup for unnecessary code is always a good practice.
  • 'null' check need to be performed wherever applicable to avoid the Null Reference Exception at runtime.
  • Avoid nested for/foreach loops and nested if conditions as much as possible.
  • Use anonymous types if code is going to be used only once.
  • Write only one statement per line.
  • Check whether any unreachable code exists and modify the code if it exists.
  • Do not use misleading names for methods. Method name should suggest its purpose.
  • If method is long consider re-factoring into separate methods.
  • Make sure that methods are having less number of lines of code. Not more than 30 to 40 lines.
  • A method should just do only single job. Do not combine multiple jobs in one method.

8Write comments on top of all methods to describe their usage and expected input types and return type information.

  • Always look for unexpected values. For example, if you use a parameter with two possible values, never assume that if the one is not matching the only possibility is the other value.
  • Use enum where necessary. Do not use numbers or strings for discrete values.
  • Use String.Empty instead of “”
  • Avoid member variables. Declare local variables where necessary and pass to other methods instead of exchanging a member variable between methods.
  • Keep member variables private and expose public/protected Properties. Do not make member variables public or protected.
  • Never hardcode a path instead use relative path.
  • Never assume that your code will run from local machine or specific drive. You never know that some users may run it from network or from a "X:”
  • At application start up, do a "self-test" and ensure that all the necessary files and dependencies are in the expected locations. Check the database connection at start up and if necessary enter a friendly message to the user in case of problems.
  • Error messages should be to assist users in order to solve the problem. Never give error messages such as "Error in Application", "It's a mistake," etc. Instead, specific messages such as "Failed to update the database”.
  • Show friendly messages to the user but log the actual error.
  • The error message should also tell what the user should do to solve the problem.
  • The event handler does not contain the code to perform the desired action. Call another method from the event handler instead.
  • Do not programmatically click a button for the same action you have written to perform click event on the button. Instead, call the same method that is called by the button click event handler.
  • Avoid large files. If a single file has more than 1200 lines of code logically divide it into two or more classes.
  • Avoid public methods and properties, if they do not really need to be accessed from outside the class.
  • Avoid too many parameters method. If you define more than 5 or 6 parameters then consider creating class instead of method.
  • If you open database connections, always close them in the finally block.
  • Logically organize all your files in appropriate folders.
  • Declare variables as close as possible to where it is first used.
  • Use StringBuilder class instead of String when you have to manipulate String objects in a loop or if multiple concatenations required to save heap memory.
  • Use implicit typing for local variables when the type of the variable is obvious from the right side of the assignment.

Example: // When the type of a variable is clear from the context, use var // in the declaration. var var1 = "This is clearly a string."; var var2 = 27; var var3 = Convert.ToInt32(Console.ReadLine());

  • Use object initializers to simplify object creation.

// Object initializer. var instance3 = new ExampleClass { Name = "Desktop", ID = 37414, Location = "Redmond", Age = 2.3 };

  • Use the concise form of object instantiation, with implicit typing.

Example: // Bad ExampleClass instance2 = new ExampleClass(); // Good var instance1 = new ExampleClass();

  • Avoid straightaway copy/pasting of code from other sources. It is always recommended to hand written the code even though if you are referring the code from some sources. By this you will get good practice of writing yourself the code and also you will understand the proper usage of that code; finally you never forget it.
  • Understand thoroughly the OOPs concepts and try implementing it in your code.
  • Take necessary steps to block and avoid any cross scripting attacks, SQL injection, and other security holes.
  • Avoid type casting and type conversions as much as possible; because it is a performance penalty.
  • Code Reusability: Extract a method if same piece of code is being used more than once or you expect it to be used in future. Make some generic methods for repetitive task and put them in a related class so that other developers start using them once you intimate them. Develop user controls for common functionality so that they can be reused across the project.
  • Code Consistency: Let's say that an Int32 type is coded as int and String type is coded as string then they should be coded in that same fashion across the application. But not like sometimes int and sometimes as Int32.
  • Code Readability: Should be maintained so that other developers understand your code easily.
  • Timely check-in/check-out of files/pages at source control (like TFS).

Tips for the Developer

  • Don't Hesitate to Ask Questions.
  • Get Familiar with the “Big Picture” of the Application.
  • Do What You Need to Do, Not What You Like to Do.
  • Share Your Knowledge and Help Your Colleagues.
  • Create a checklist for yourself of the things that the code reviews tend to focus on.
  • Understand and accept that you will make mistakes. The point is to find them early, before they make it into production.
  • No matter how much knowledge and experience you have, someone else will always know more. Such an individual can teach you some new moves if you ask. Seek and accept input from others, especially when you think it’s not needed.
  • Don’t rewrite code without consultation.
  • The only constant in the world is change. Be open to it and accept it with a smile.
  • Fight for what you believe, but gracefully accept defeat. Understand that sometimes your ideas will be overruled.
  • Don’t be “the guy in the room.” The guy in the room is out of touch, out of sight, and out of control and has no place in an open, collaborative environment.

Check-in/Check-Out Mechanism for TFS

You all may already be aware of TFS and its usage to effectively work as a Team on a Team Project but I thought to reassemble some of the important points/steps to ensure good Productivity. So please read the below points.

This would really help especially if 'Multiple Checkout' option is enabled.

Key Points/Steps

  • Always make it a practice to Get the latest version of the Project daily morning before you start your work.
  • Build/Rebuild your solution to ensure that there are no build errors.

If you get any build errors, check what those are. Suppose they are simple to resolve like 'Broken Reference' errors or any other simple errors; please take initiative and resolve them. If you notice that they belong to some other Team member's task, please intimate him/her so that they could fix it.

  • Check out the file(s) which are relevant to your task and start working. Once you are done with your work, verify it by building the project. And if you don't find any build errors; run the project and test your page whether it is working fine. If it's fine, check in your files. If you find any build errors or runtime issues, then resolve them and then checkin.

It's always a good practice to divide a big Task in smaller tasks and on each sub task's success, you can check in your work. For example: UI design, populating dropdowns, placing validations, saving form data, displaying grid data, etc. can all be treated as individual sub tasks for a particular page functionality. This will ensure that you will not have any pending check ins at the end of the day and also it keeps things easy. If a sub task is taking a longer time and if you want to continue it the next day, you can comment your partial written code and check in the file. The next time you start work you can checkout, uncomment your code and start working. This practice will minimize the usual conflicts we get when we are working under 'Multiple checkout' option enabled and also it will not have any impact if TFS connectivity issue occurs.

  • Sometimes when we take the latest version from TFS, we get some conflicts in some files, check these conflicts carefully; and if the files don't belong to you, you can straightaway choose the option 'Resolve Conflicts'. Then VS/TFS takes care to automatically resolve conflicts for you. And if a file belongs to you on which you recently worked on; then most of the times you have to choose 'Auto Merge' option so that your changes and the last guy who has checked in recently, his changes, would be automatically merged and saved to TFS. And still if you feel you have to cross verify the changes, you can trace them in 'Merge Tool' option and then merge it.
  • Till now, the check-in and check-out process that we discuss is for the existing files in our project but there is a slight difference in case of adding a new file, renaming a file, or deleting a file. As TFS and your project already have metadata reference/info of your existing files, hence it only checks out the file when you start making any changes or if you explicitly check it out, but it will not check out your project.

Conclusion

I welcome feedbacks, queries, and suggestions from the readers so that I can improve it further and get some benefit out of it. Your inputs, clarifications, and feedback in this regard would be highly appreciated.