Page History: Jetfire Code: Hints for Writing Good Code

Compare Page Revisions

« Older Revision - Back to Page History - Newer Revision »

Page Revision: 2009/07/29 00:02

Table of Contents [Hide/Show]

   Jetfire Code: Hints for Writing Good Code
      Structure Hints
      Syntax Hints
      Semantic Hints

Jetfire Code: Hints for Writing Good Code¶

This page contains a number of suggestions that may help in writing good Jetfire code. The suggestions include:

Structure Hints
Syntax Hints
Semantic Hints

Structure Hints¶

Keep the size of the code files small.
Follow indentation practices to make your code easy to read.

Follow the code template. TrackerRealm marks Jetfire code as GNU GPL. Decide how you copyright your code and add it to the top of the code file.


// TheNameOfTheWorkflow    W O R K F L O W
//===================================================================================
// TheNameOfTheFile.txt
//===================================================================================
// Copyright (C) 2009 TrackerRealm Corporation
// This file is part of Jetfire.  http://Jetfire.ca
// 
// Jetfire is open software: you can redistribute it and/or modify it under the terms of the 
// GNU General Public License as published by the Free Software Foundation, version 3 of the License.
// 
// Jetfire is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; 
// without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  
// See the GNU General Public License for more details.
// 
// You should have received a copy of the GNU General Public License along with Jetfire.  
// If not, see http://www.gnu.org/licenses.
// REMOVAL OF THIS NOTICE IS VIOLATION OF THE COPYRIGHT.
//===================================================================================
// This code does the following:
// * List of features

namespace TheNamespace { // This workflow provides a Base Class for associating Questions and Answers. public workflow TheNameOfTheWorkflow { } }

The namespace and workflow class name forms a unique name that identifies the code that you write. e.g. the namespace, JetfireApps is used for the Jetfire code applications written by TrackerRealm. You do not need to have a separate namespace for every Jetfire code class. Pick a namespace that is meaningful and memorable.
The namespace and workflow class name forms a unique name that identifies the code that you write. e.g. pick a workflow class name that is meaningful and succinct.

Syntax Hints¶

Add Comments to your code.
- No matter how small the code foot-print is, people forget what code does after a certain time.

Use the C# 3.0 syntax for writing properties


// SomeProperty stores something.
// Note that this property can be read and written by anyone.
public string SomeProperty
{
get;
set;
}

Keep states and access in the same order. This makes it easy to read and compare properties and methods in the workflow.


// SomeProperty stores something.
// The states access modifier is added before the access access modifier.
public string SomeProperty : states(SomeState), access("SomeRole")
{
get;
set;
}

Semantic Hints¶

Last time updated
- Some workflows require that a timestamp be updated in the workflow every time that the workflow is updated. This can easily be done by adding a 'LastUpdated' property to the workflow and updating it in the Save Method.
```
// Store the Last time that the workflow was updated.
// Note the use of the private access modifier.  This property can only be set from within the workflow
public DateTime LastUpdated
{
get;
private set;
}
```
Save Methods
- There are a number of situations where a Jetfire Save Method is called when data is saved to a workflow in a Jetfire Web Part. e.g.
  - Jetfire code can be used to validate whether the user has added all of the necessary properties.
  - Updating a Last Update timestamp.
- Create a save method that is added to the Jetfire Web Part (the Edit Property of the Web Part is called 'Save Method'.)
```
// Add the name of this method to the 'Save Method' Edit Property of the Jetfire Web Part.
public void FinishEdit()
{
// Update the Last time that the workflow was saved when the Workflow is saved.
LastUpdate = DateTime.Now;
}
```

   // Check if the first and last variables are blank when the workflow is saved.
   public void FinishEdit()
   {
      if (first == "")
         throw exception("Enter First Name");
      if (last == "")
         throw exception("Enter Last Name");
   }

Use throw exception in Jetfire Code to identify an error.
- When throw exception is encountered in Jetfire Code, an error is generated and appears in the Jetfire Web Part as a message. In the above code "Enter First Name" is displayed to the user when the first name is not input on the Web Form.
Naming State and Methods
- States and Methods can be confusing when combined in a workflow because they look so similar. Here are a couple of conventions that you can use to reduce the confusion.
  - The state name is 'Delete'. Methods that promote the state to Delete are prefixed with 'Promote_To_'.
  - Use past tense for state names, e.g. 'Deleted'. Use present tense for methods, e.g. 'Delete'.
```
public Delete() { }
public Promote_to_Delete()
{
enterstate Delete();
}
```

   public Deleted() { }
   public Delete()
   {
      enterstate Deleted();
   }