Difference between revisions of "Coding guideline - CatGlobe"

From Catglobe Wiki
Jump to: navigation, search
Line 3: Line 3:
 
This guideline contains CatGlobe-specific coding rules.  
 
This guideline contains CatGlobe-specific coding rules.  
  
== Exception ==
+
== Exception ==
  
=== Exception handling ===
+
=== Exception handling ===
  
*Only catch exception if you can do some thing with it.
+
*Only catch exception if you can do some thing with it.  
*All re-thrown exception must include the original exception in its inner exception.
+
*All re-thrown exception must include the original exception in its inner exception.  
*DO: always catch specific exception type. You are allowed to catch generic exception and re-throw a specific exception; for example in CGScript all exceptions are caught and a RuntimeException is re-thrown afterward.
+
*DO: always catch specific exception type. You are allowed to catch generic exception and re-throw a specific exception; for example in CGScript all exceptions are caught and a RuntimeException is re-thrown afterward.  
 
*DO NOT: empty and undocumented catches; using unspecific catches, unless they are documented well in the design document and are approved by the PMs.
 
*DO NOT: empty and undocumented catches; using unspecific catches, unless they are documented well in the design document and are approved by the PMs.
  
=== Create a new custom of exception ===
+
=== Create a new custom of exception ===
  
*Naming rule: the new exception must be suffixed with “Exception”.
+
*Naming rule: the new exception must be suffixed with “Exception”.  
*All custom exceptions must inherit from another exception class.
+
*All custom exceptions must inherit from another exception class.  
*The exception should be serializable in order to use in CatTask service. Refer to [[Serializable exceptions]] for more details. Notice: when the new CatTask service is done, this may be obsolete.
+
*The exception should be serializable in order to use in CatTask service. Refer to [[Serializable exceptions]] for more details. Notice: when the new CatTask service is done, this may be obsolete.  
 
*Namespace rule:
 
*Namespace rule:
  
        - If the being created exception is used in multiple places, it must be placed in the CatGlobe.Framework.Exceptions namespace.
+
        - If the being created exception is used in multiple places, it must be placed in the CatGlobe.Framework.Exceptions namespace.  
  
        - Otherwise, if it is used for a specific class only, it can be placed in the namespace where it is used.
+
        - Otherwise, if it is used for a specific class only, it can be placed in the namespace where it is used.  
 +
 
 +
== Working with threads ==
 +
 
 +
*Usages of threads must be specified in the Technical design and approved by PMs.
 +
*Use CatGlobe.Framework.Security.AsyncHelper class to start a thread with auto-impersonate, access factory and webconfig manager.
 +
 
 +
== Web pages – web controls ==
 +
 
 +
=== Code behind (ASPX and ASCX) ===
 +
 
 +
*Code behind must be documented with request parameters, usage, purpose.
 +
*Use Register…(JavascriptConstant…) to include javascript files in the code behind.
 +
*Web page must inherit from the PageBase class, control must inherit from the ControlBase class and Web Service must inherit from the WebServiceBase class.
 +
*DO NOT override the OnError event, unless it is approved in the technical design.
 +
 
 +
=== ASPX file ===
 +
 
 +
*Replace the auto-generated DOCTYPE by this one: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >
 +
*A page must have a title using text resource.
 +
*All the validation warnings which the Visual Studio shows must be fixed.
 +
*Adding references to user controls and using of tagPrefixes: must following this guideline [[Tag prefixes for user controls and web controls]]
 +
*You are allowed to reference to javascript files in the aspx files directly. However, you must use the JavascriptConstant to reference to them.
 +
*If a page or a control contains more than 3 methods or more than 20 lines, move it to a separate js file.
 +
 
 +
=== ASCX file ===
 +
 
 +
*DO NOT reference to javascript files in the ascx files.
 +
 
 +
=== Text resources ===
 +
 
 +
*When you need to register a text resource to the client side, use the PageBase.CGClientScript.RegisterTextResource method. The method will encode registered text resources for you.
 +
*Setting for text resource files of web pages:
 +
 
 +
        - Need to be set to the [filename].aspx.resx file only.
 +
 
 +
        - Custom tool namespace: x (yes, only the letter 'x').
 +
 
 +
        - Build action: None
 +
 
 +
        - Custom tool: ResXFileCodeGeneratorEx
 +
 
 +
*Setting for text resource files of an enumeration file:
 +
 
 +
        - Custom tool namespace: aenum
 +
 
 +
        - Build action: Embedded Resource
 +
 
 +
        - Custom tool: ResXFileCodeGeneratorEx

Revision as of 03:39, 17 December 2008

Introduction

This guideline contains CatGlobe-specific coding rules.

Exception

Exception handling

  • Only catch exception if you can do some thing with it.
  • All re-thrown exception must include the original exception in its inner exception.
  • DO: always catch specific exception type. You are allowed to catch generic exception and re-throw a specific exception; for example in CGScript all exceptions are caught and a RuntimeException is re-thrown afterward.
  • DO NOT: empty and undocumented catches; using unspecific catches, unless they are documented well in the design document and are approved by the PMs.

Create a new custom of exception

  • Naming rule: the new exception must be suffixed with “Exception”.
  • All custom exceptions must inherit from another exception class.
  • The exception should be serializable in order to use in CatTask service. Refer to Serializable exceptions for more details. Notice: when the new CatTask service is done, this may be obsolete.
  • Namespace rule:

        - If the being created exception is used in multiple places, it must be placed in the CatGlobe.Framework.Exceptions namespace.

        - Otherwise, if it is used for a specific class only, it can be placed in the namespace where it is used.

Working with threads

  • Usages of threads must be specified in the Technical design and approved by PMs.
  • Use CatGlobe.Framework.Security.AsyncHelper class to start a thread with auto-impersonate, access factory and webconfig manager.

Web pages – web controls

Code behind (ASPX and ASCX)

  • Code behind must be documented with request parameters, usage, purpose.
  • Use Register…(JavascriptConstant…) to include javascript files in the code behind.
  • Web page must inherit from the PageBase class, control must inherit from the ControlBase class and Web Service must inherit from the WebServiceBase class.
  • DO NOT override the OnError event, unless it is approved in the technical design.

ASPX file

  • Replace the auto-generated DOCTYPE by this one: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >
  • A page must have a title using text resource.
  • All the validation warnings which the Visual Studio shows must be fixed.
  • Adding references to user controls and using of tagPrefixes: must following this guideline Tag prefixes for user controls and web controls
  • You are allowed to reference to javascript files in the aspx files directly. However, you must use the JavascriptConstant to reference to them.
  • If a page or a control contains more than 3 methods or more than 20 lines, move it to a separate js file.

ASCX file

  • DO NOT reference to javascript files in the ascx files.

Text resources

  • When you need to register a text resource to the client side, use the PageBase.CGClientScript.RegisterTextResource method. The method will encode registered text resources for you.
  • Setting for text resource files of web pages:

        - Need to be set to the [filename].aspx.resx file only.

        - Custom tool namespace: x (yes, only the letter 'x').

        - Build action: None

        - Custom tool: ResXFileCodeGeneratorEx

  • Setting for text resource files of an enumeration file:

        - Custom tool namespace: aenum

        - Build action: Embedded Resource

        - Custom tool: ResXFileCodeGeneratorEx