Difference between revisions of "Coding guideline - CatGlobe"
| 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 04:39, 17 December 2008
Contents
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
