DEVTOME.COM HOSTING COSTS HAVE BEGUN TO EXCEED 115$ MONTHLY. THE ADMINISTRATION IS NO LONGER ABLE TO HANDLE THE COST WITHOUT ASSISTANCE DUE TO THE RISING COST. THIS HAS BEEN OCCURRING FOR ALMOST A YEAR, BUT WE HAVE BEEN HANDLING IT FROM OUR OWN POCKETS. HOWEVER, WITH LITERALLY NO DONATIONS FOR THE PAST 2+ YEARS IT HAS DEPLETED THE BUDGET IN SHORT ORDER WITH THE INCREASE IN ACTIVITY ON THE SITE IN THE PAST 6 MONTHS. OUR CPU USAGE HAS BECOME TOO HIGH TO REMAIN ON A REASONABLE COSTING PLAN THAT WE COULD MAINTAIN. IF YOU WOULD LIKE TO SUPPORT THE DEVTOME PROJECT AND KEEP THE SITE UP/ALIVE PLEASE DONATE (EVEN IF ITS A SATOSHI) TO OUR DEVCOIN 1M4PCuMXvpWX6LHPkBEf3LJ2z1boZv4EQa OR OUR BTC WALLET 16eqEcqfw4zHUh2znvMcmRzGVwCn7CJLxR TO ALLOW US TO AFFORD THE HOSTING.

THE DEVCOIN AND DEVTOME PROJECTS ARE BOTH VERY IMPORTANT TO THE COMMUNITY. PLEASE CONTRIBUTE TO ITS FURTHER SUCCESS FOR ANOTHER 5 OR MORE YEARS!

Coding Guidelines

Purpose

This is not a set of guidelines on how to code, but a set of guidelines on how to make for a more consistent set of coding standards within your development team.

Obviously if you think anything in the guidelines don’t make sense or there are items that you feel should be handled differently, please feel free to code as would be best in your team

Architecture

Most projects that are worth embarking will benefit from a proper separation of concerns. No one single pattern is going to fit all situations but there are some general guidelines that will help to promote a quality, scalable, and maintainable code base. New projects should not use the old WebForms ASP.Net framework because it does nothing to promote separation of controller and presentation logic. Instead new projects should implement one of the more widely accepted patterns such as MVC.

Projects of any reasonable size should be split into tiers. Usually a three tier solution containing a presentation layer, a business logic layer, and a data access layer should be implemented. Each layer should only ever communicate with its neighboring layer/tier i.e. the presentation layer should never directly communicate with the Data Access Layer. This helps separate validation, business logic and data connectivity to provide a more maintainable, easier to follow solution with more potential for reuse. To allow data to be shared between data access and business logic layers, either created an additional layer (business objects layer) or pass them via an abstraction of some sort such as datatables and datasets in .Net.

A component based architecture should always be followed and where cross platform communication is required a Service Oriented Architecture should be implemented. Any Service Oriented Architecture based developments must be as fast as possible given the boundaries (in .Net WCF enables us to achieve this on multiple levels using bindings - see http://msdn.microsoft.com/en-us/library/ms733769.aspx). Patterns & Practices

Patterns and practices that help create a loosely coupled architecture such as SOLID and DRY should be employed but these should always be held in contention with principles that prevent over-engineering of solutions such as YAGNI. All developers should strive to understand and implement these principles in their solutions.

Legacy applications should not be re-architectured just because they are out of date. In general most applications that have been around a while have stood the test of time regardless of how bad they may appear behind the scenes. If the code is deemed impossible to work with then it should be audited and the benefits of replacing or reworking the solution should be weighed up fairly against the costs and risks associated with it.

Libraries and tools such as ORMs should be used where possible to avoid writing too much code and reinventing the wheel. As a word of caution, libraries that are not in widespread use or are not well documented should (in general) be avoided because it is harder to fix problems with them should anything go wrong.

Common patterns should always be used to solve common problems (see: http://www.dofactory.com/Patterns/Patterns.aspx/).

Namespaces & svn layout

In the past, the general convention was to use a format of <companyname>.<technology>.<projectname>.<BLL> etc but this convention fails to appreciate that the BLL and DAL layers might be shared between technologies. Some projects will already exist in the new repository with names that do not match this pattern; please try to stick to the new naming conventions rather than following the old naming structure.

Going forward the convention for namespaces and svn project layout is as follows: For applications Namespace: foo.prj.<solutionname>.<technology> For application solutions we group the projects using the same structure as we see in visual studio.

Example:

Solution: C:\svn\foo\trunk\Solutions\foo.prj.myexampleapp

  • C:\svn\foo\trunk\Solutions\foo.prj.myexampleapp\foo.prj.myexampleapp.web
  • C:\svn\foo\trunk\Solutions\foo.prj.myexampleapp\foo.prj.myexampleapp.win
  • C:\svn\foo\trunk\Solutions\foo.prj.myexampleapp\foo.prj.myexampleapp.console
  • C:\svn\foo\trunk\Solutions\foo.prj.myexampleapp\foo.prj.myexampleapp.bll
  • C:\svn\foo\trunk\Solutions\foo.prj.myexampleapp\foo.prj.myexampleapp.dal

Svn location: http://dev-sql:8080/svn/foo/trunk/Solutions/MySolutionName

  • //dev-sql:8080/svn/foo/trunk/Solutions/MySolutionName/foo.prj.myexampleapp.web *//dev-sql:8080/svn/foo/trunk/Solutions/MySolutionName/foo.prj.myexampleapp.win
  • //dev-sql:8080/svn/foo/trunk/Solutions/MySolutionName/foo.prj.myexampleapp.console *//dev-sql:8080/svn/foo/trunk/Solutions/MySolutionName/foo.prj.myexampleapp.bll
  • //dev-sql:8080/svn/foo/trunk/Solutions/MySolutionName/foo.prj.myexampleapp.dal For utility libraries Namespace: foo.lib.<technology>.<libraryname> For utility libraries we will group the libraries by technology to avoid cross cutting concerns. Any libraries that are stored under foo.lib.Web.*** must not contain any references to windows components, vice versa for foo.lib.Windows. Any foo.lib.Generic libraries must not have any references to windows or web components. Examples of valid technology names are (Win, Web, Generic) Example: Library: C:\svn\foo\trunk\Libraries\foo.lib.win.MyWinFormsLib Svn location: //dev-sql:8080/svn/foo/trunk/Libraries/foo.lib.win.MyWinFormsLib

Referencing library files

External

When referencing external library files from 3rd parties make sure that you reference the library file from the binaries folder under a shared public drive that all your developers can access. If you come across any projects that are using library files from anywhere else please report it to the development manager, copy the files to the correct location, re-reference them and re-build the relevant solutions.

Internal

When referencing internal library files, you should not be referencing the project files themselves as you have no idea when someone might change one of the files in this library project and cause your project to break.

Naming Conventions

.Net Naming Conventions Historically, Hungarian notation (str, int etc. prefixes) has been the norm. It used to be the Microsoft recommendation and it made sense to use it in a weakly typed language like VBScript. However, the MS recommendation is now to avoid Hungarian notation.

Camel case (userID) for parameters and local variables Pascal Case (UserFirstName) for class, method names, properties enumerations and everything else Don’t use underscores between words – UserFirstName not User_First_Name Avoid use of public variables, favouring public properties instead Avoid abbreviations where possible

Additions and Exceptions

For private variables inside a class, prefix with an underscore - _userID For constants, use all caps – MAILHOST For web controls, we still use Hungarian notation because there’s still added value knowing whether we’re coding against (e.g.) a Textbox or a Label.

Prefixes for Common Web Controls

  • Button – btn
  • CheckBox – chk
  • CheckBoxList – chkl
  • CustomValidator – ctv
  • DataGrid – dg
  • DropDownList – ddl
  • HyperLink – hyp
  • Image – img
  • ImageButton – ibtn
  • Label – lbl
  • LinkButton – lbtn
  • ListBox – lst
  • ListView – lvw
  • Literal – lit
  • Panel – pnl
  • PlaceHolder – plh
  • RadioButton – rdo
  • RadioButtonList - rdol
  • Repeater – rep
  • TextBox – txt
  • ValidationSummary – vals

Prefixes for Common ADO.NET Types

  • ArrayList – al (non ADO.NET)
  • Command (generic) – cmd
  • Connection (generic) – cn
  • DataAdapter – da
  • DataColumn – dc
  • DataReader (generic) – dr
  • DataRow – drw
  • DataSet – ds
  • DataTable – dt
  • DataView – dv

All Stored Procedures should begin usp_. This should then be followed by entity that they act on, followed by an underscore then the action that they perform. Example: usp_Advert_GetAdvertDetails. This ensures that relevant stored procedures remain together when viewed in the default alphabetical order within SQL Enterprise. This naming convention will normally closely match with the related class name method making the call (e.g. Advert.GetAdvertDetails etc.) Table names should not be prefixed with tbl, and should be in PascalCase and should not contain underscores Field names within tables should not be prefixed with any data type abbreviations Any SQL jobs should be named as follows: “Database Name - Job Description” → Example “CaravanSelecta - Purge”

Configuration Settings, globals & “magic variables”

The Web.config (or App.config) file should contain all settings. Such settings might include Paths, URL’s, Connection Strings, Admin E-mail addresses etc. Consider using custom configuration sections for common components and when you want to avoid cluttering the web.config file with too many settings (http://msdn.microsoft.com/en-us/library/2tw134k3.aspx). Global variables are evil - don’t use them in general Singletons are pretty evil - use them with caution Magic variables belong in a config file or well named constant variable e.g: circleArea = 3.142*radius2 is not as meaningful as PI*radius2

Code Formatting

Use code regions (#region) where appropriate but favour splitting code into logical methods and classes as this is clearer still. Don’t place multiple statements on a single line.

Where areas of code are incomplete, use the TODO ‘token’, followed by a brief comment summarizing what work still needs to be done. This makes it easier to find all the areas of incomplete code that need to be sorted before testing/deployment. You can see a complete list of all ‘TODO’ areas within your project by going to the View > Task List, then select Comments from the drop down list in the panel that appears at the bottom of the screen.

Source Control

We are now using SVN for code control. Please read the “Code Repositories Standards & Procedues” document for information on how to use SVN and the approach you should take when using SVN and when releasing code.

Documentation

Any documentation that is associated with a given project should be placed within a /Docs/ subfolder within your solution folder and must be marked “do not copy” to prevent it being deployed when published. Such documentation might include original Specs, amended specs, flow diagrams etc.

Environments

Development Environment

When creating a project you must make sure that you provide a dedicated development environment and set the project up in such a way that if grabbed by another developer to work on, the project can be run without fear of affecting live systems or live customers (email senders in particular). This should be set up as the default so that if a developer was to just hit run, they should have no concerns about what it might be doing. It is worth pointing out that this has not been the case for a number of years so if you do come across a project with no development environment, you should create a development environment for the project.

In the case of windows applications this is often difficult to achieve fully due to the fact that some systems in place do not have a dev equivalent either. Where possible you should “stub” around the systems so that development and testing can be performed without worry.

Test Environment

A dedicated test environment makes it much easier for test personnel to test programs without new development work affecting the tests. This is something we should work towards achieving with new and large development projects. Where testing is proving difficult with only a dev environment, we should look to add testing environments for these projects / systems as a priority.

Error Handling

Please make sure that when you handle exceptions you log the error somewhere. There should never be a need to swallow exceptions completely. If do need to swallow an exception and continue (say in the case of a service or a webservice consumer), you should at least log the exception before continuing. If you do ever swallow an exception completely please make a comment to say why it is you are doing this (something like, the program errored when logging the error might be reasonable but must be commented on).

When logging errors in a web application Elmah has proved to be a very effective way to log errors for Asp.Net websites. If you need to log errors for windows applications you should use log4net instead.

More info @ log4net tutorial. & elmah wiki

Extra Bits

Rackspace Cloud Files and the CDN can be used for images and static content (be aware there is a 72 hour TTL set on most containers but this is variable) LessCss or dotLess to be used for CSS All javascript should be minified before deployment

Security

Appropriate effort should be made to ensure all code is secure and prevents against common attacks. For example, all solutions where passwords are stored should be hashed or encrypted and all sql should be written in such a way as to prevent against SQL injection attacks. Any concerns regarding existing solutions should be raised with a development manager for due consideration.

Closing Comments

This is by no means a complete set of guidelines and there are always standards variations, even within organizations such as Microsoft themselves. However, consistency is key, and if within the development team here we can each try to remain as consistent with our standards as possible, it will benefit everyone.

If anyone ever has anything they wish to add to this set of standards, or feels there is a more effective approach to anything within this document, please make yourself heard.

References

  • McConnell: Code Complete (2nd Edition)
  • Microsoft Press: Practical Guidelines and Best Practices for Visual Basic & Visual C# Developers
  • Microsoft Press: Practical Standards for Visual Basic.NET
  • Enterprise Solution Patterns Using Microsoft .NET (http://msdn.microsoft.com/en-us/library/ff647095)

Categories


QR Code
QR Code coding_guidelines_and_standards (generated for current page)
 

Advertise with Anonymous Ads