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. Whitespace makes code easier 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.
//===================================================================================
// DisplayName: 'Friendly name for the class'
// 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.
- Workflows can contain other workflows to build complex relationships. When adding a child workflow to the parent workflow, 'return the workflow' to the calling method.
// A list property in the parent workflow.
public List WorkflowList
{
get;
private set;
}
// Create a workflow and return it to the calling method.
public MyWorkflow AddMyWorkflow()
{
// Create a workflow.
MyWorkflow w = new MyWorkflow();
// the new workflow is added to a list in the parent workflow to create a reference.
WorkflowList.Add(w);
// the new workflow is returned so that the calling method can use it directly.
return w;
}
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 States and Methods
- States and Methods can be confusing when combined in a workflow because they look 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'.
Convention a) prefix methods with 'Promote_to_'
public Delete() { }
public void Promote_to_Delete()
{
enterstate Delete();
}
Convention b) use present tense for methods
public Deleted() { }
public void Delete()
{
enterstate Deleted();
}
- Only Logged in users can set a property
- Jetfire code supports dynamic access modifiers. This means that the Workflow Designer can identify who can set or get properties and execute methods. A typical requirement is that a property be set by anyone EXCEPT Guests.
- The following pattern is used to prevent Guests from setting the property.
- The 'IsNotGuest' method can be used as an expression in the access evaluation or as a regular method called from other Jetfire Methods.
public string MyFavoriteProperty
{
get;
set : access(IsNotGuest);
}
public bool IsNotGuest()
{
return User.Login.Name != "Guest";
}