Difference between revisions of "Coding guideline - CatGlobe"
| Line 104: | Line 104: | ||
*Functions must be documented about their usages and their parameters. Types of parameters must also be specified. | *Functions must be documented about their usages and their parameters. Types of parameters must also be specified. | ||
*In order to utilize the intellisense feature of VS2008: | *In order to utilize the intellisense feature of VS2008: | ||
| + | |||
| + | - Put summary inside function: | ||
| + | |||
| + | [[Image:Javascriptsummary.jpg]] | ||
| + | |||
| + | *To get intellisense work in a javascript file, you have to add a reference to the source JavaScript file. There are two situations need to be considered here: | ||
| + | |||
| + | - If the source JavaScript file is a embedded resource, use the declaration below: | ||
| + | <blockquote> /// <reference name="registered name of that embeded JavaScript file" /> </blockquote> | ||
| + | - If the source JavaScript file is an included file, use the declaration below: | ||
| + | |||
| + | /// <reference path="path file name of that JavaScript file"/> | ||
| + | |||
| + | [[Image:Javascriptreference.jpg]] | ||
| + | |||
| + | *To get intellisense work in a ASPX file: | ||
| + | |||
| + | - If your page is implementing AJAX, reference to the source JavaScript file in ScriptManager control: | ||
| + | |||
| + | <asp:ScriptManager runat="server" id="scriptManager"><br><Scripts><br><asp:ScriptReference path="virtual path file name of the JavaScript file" /><br></Scripts><br></asp:ScriptManager> | ||
| + | |||
| + | - Otherwise, reference to the source JavaScript file in a script element declaration: | ||
| + | |||
| + | <script src="virtual path file name of the JavaScript file" type="text/javascript" > | ||
=== === | === === | ||
[[Category:Technical_guidelines]] | [[Category:Technical_guidelines]] | ||
Revision as of 04:37, 18 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
Events handling
- When you override an event, always call to base class method.
- Only handle an event when you have something to do with it. On this example, the OnInit method should be removed because we have nothing to do with it:
protected override void OnInit(EventArgs e)
{
base.OnInit(e);
}
Request
- All the arguments which can be passed to the url must be documented.
- Each request parameter must have it own getter property. Handling of the request parameters must always be inside the getter properties.
- All request parameter getters must be put in a region called “REQUEST PARAMETERS”.
Session
- Use SessionManager to work with Session.
- Objects which are put into the Session must be serializable.
- Examples about good and bad usages of Session, in the share-data-between-pages context:
- Good if the data is complicated and cannot be render to the clientside or pass via url easily. A good example is the search criterion of the search page.
- Good if the data is incompleted, so it is not ready to be saved to the database yet, for example the data which is collected through a wizard: we collect some pieces of information in step 1, put them into Session and navigate to the step 2, and so on...
- Good if the data takes too much resources (IO, CPU, time) to retrieved. For example a fully-initialized Questionnaire, means all of its questions, question properties, sub questions, answer options are initialized.
- Bad if the data in Session can be changed by multiple pages/forms by multiple ways. For example: the page A shows some information about a report, which is put in the session. The user opens the Report compact dialog in another tab. When the user saves the report in the CRD, it is the database is updated, not the report object in the Session. Now the user backs to the page A and modifies the report. Obviously he will get a concurrency problem.
Javascript
- Do not use browser-specific script. All the javascript must work in both IE and FireFox.
- Javascript should be written in OOP style using AJAX .NET. One class should be in one file.
- Functions must be documented about their usages and their parameters. Types of parameters must also be specified.
- In order to utilize the intellisense feature of VS2008:
- Put summary inside function:
- To get intellisense work in a javascript file, you have to add a reference to the source JavaScript file. There are two situations need to be considered here:
- If the source JavaScript file is a embedded resource, use the declaration below:
/// <reference name="registered name of that embeded JavaScript file" />
- If the source JavaScript file is an included file, use the declaration below:
/// <reference path="path file name of that JavaScript file"/>
- To get intellisense work in a ASPX file:
- If your page is implementing AJAX, reference to the source JavaScript file in ScriptManager control:
<asp:ScriptManager runat="server" id="scriptManager">
<Scripts>
<asp:ScriptReference path="virtual path file name of the JavaScript file" />
</Scripts>
</asp:ScriptManager>
- Otherwise, reference to the source JavaScript file in a script element declaration:
<script src="virtual path file name of the JavaScript file" type="text/javascript" >
