Style Guide for Writing Sample Programs

We produce sample programs for all Open Market APIs. To improve the look and consistency of sample programs across all our products, we'd like everyone to follow certain coding guidelines.

We produce sample code in five different languages:

C
C++
Java
XML
HTML

C Programming Language

We provide sample C programs for the following APIs:

SecureLink API
Buyer Profile API
Order Entry API
Multi-Item API

This section describes the style guidelines for coding sample C applications.

General Rules

The start of every sample C program


/*************************************************************
 * program_name.c
 *
 * Description of what the program does.
 * (Could be many lines.)
 *
 * Copyright (c) [year] Open Market, Inc. 
 * All rights reserved.
 *************************************************************/

Writing block comments


/**********************************
 * Like this.
 * Can easily add more text. 
 **********************************/

Writing inline comments

/* like this */

Naming your programs

Should start with lowercase letter
Should start with verb
Use underscores instead of white space

For example:

create_digital_offer.c   /* good program name */
CreateDigitalOffer.c     /* bad program name */
digital_offer.c          /* bad program name */

Naming your functions

Should start with capital letter
Should start with verb
Should be mixed case, without underscores
Functions that initialize (allocate memory, for example, in BPAPI applications) should typically be named Init.
Functions that clean up (deallocate memory that had been allocated by Init should typically be named CleanUp.

For example:

PrepareDatabase();   /* good function name */
prepare_database();  /* bad function name */
database();          /* bad function name */

Naming your variables

Should be in lowercase (to distinguish from function names and constants).
Should use underscores to connect variable names that contain multiple words.
Should be highly descriptive.

For example:

transaction_server   /* good variable name */
transactionserver    /* bad variable name (needs underscore) */
ts                   /* bad variable name (too ambiguous) */

What the main() function should do

Should be as short as possible
Should primarily consist of function calls

How to specify exit codes

Sample code should contain #define'd exit codes.
0 is reserved for successful error-free exit.

Example:
#define SUCCESS 0
#define FILE_NOT_FOUND  1
#define COULD_NOT_CONNECT_WITH_TRANSACT 2

Using the preprocessor directives #debug and #verbose Should not be in production sample code but may be in courseware code.

What to name the variable that holds a function's return value. return_code

What to name variables in BPAPI programs

Data Structure	Variable Name
OMTX_Handle	transact_handle
OMTX_MUBuyerProfile	buyer_profile
OMTX_MUCustomField	custom_field (not CustomFields)
OMTX_MUHandle	mu_handle
OMTX_MUUserDetails	user_details

An Example C Function

Here is a sample C function. An explanation follows.


1  
2  /******************************************************************
3    * This function is useful for debugging.  It will write the 
4    * current contents of OSL_Order to file ./current_order.txt
5  ******************************************************************/
6  void
7  WriteOrderToExternalFile(void)
8  {
9   OSL_Status  return_code;
10   OSL_DString dynamic_string;
11   OSL_Error   error;
12   
13   
14   /*****************************************
15    * Create an unpopulated dynamic string. 
16    *****************************************/
17     return_code = OSL_MakeDString(&dyanmic_string, &error);
18     if (Status != OSL_NO_ERROR)  {
19       fprintf(stderr, "OSL_WriteOrderToDString Failure: %d\n", 
20                       error.message);
21       return;
22     }
23  
24   /*****************************************
25    * Loop like it's 1999. 
26    *****************************************/
27     for (count=2000; count>1998; count--)  {
28       running_total += count;
29       printf("%d\n", running_total);
30     }
31  }

Line(s)	What To Do On This Line
1	Put a blank line between functions.
2-5	Describe the function.
6	Specify the function's return type on a separate line.
7	Specify the function's name and its parameters. If the function has only one parameter, specify the function name and parameter on the same line. If the function has multiple parameters, specify one parameter per line.
8	Place the opening brace { flush left just after the last function parameter.
9-11	Specify all local function variables starting at column 1.
17, 18, 22, 27, 30	Outer level code should start at column 3.
19-21, 28-29	Embedded code should start at column 5.
18, 27	The starting brace should start at the end of a line (not on its own line).
22, 30	The closing brace should be aligned with the outer level code (for example, with `for` and `if`.

Word Usage in Text

When describing C programs in your programmer guides, follow these guidelines:

Correct Term	Incorrect Term	Comment
function	call	May use "call" as verb, but not as noun.
parameter	argument
user name	username
`FunctionName()`	`FunctionName`	Add parentheses at end when citing function name in text.
Content Server	local server, store server, or web server

C++ Coding Rules

(The doc department modified (slightly) engineering's guidelines for C++.)

We provide sample C++ applications for all Transact APIs, including:

Fulfillment API
Payment API
Microtransactions API
Transact Utilities
Order Capture API
User Services API

If you are writing fresh C++ examples or modifying some existing ones, then we'd like you to follow these coding guidelines.

We code two different categories of C++ programs:

NonCOM applications
COM modules

NonCOM Applications

First off, we (the doc department) aren't writing classes and header files. Rather, we are demonstrating how to instantiate classes that are part of the APIs. Therefore, our sample C++ applications look a lot like sample C applications; that is, they contain a main() function and possibly a bunch of secondary functions called from main(). In fact, because context variables don't work too well as function parameters, our main() functions have a tendency to be quite long.

Most C++ applications have roughly the same start, which is:

Collecting credential information (their user name and password) from the user.
Invoking TTransactAPIService2.Login() to test the credentials.
Creating at least one context.

Validating the context(s).

Copy the existing starting code for your API or a related API.

Secondary Functions

Most nonCOM applications require two secondary functions:

HresOut
OutputLatin1

Paste the following code into the top of every nonCOM application:


/////////////////////////////////////////////////////////
// HresOut evaluates an HRESULT.  If the HRESULT is
// an error code, HresOut outputs an appropriate message,
// and terminates the program.
/////////////////////////////////////////////////////////
static void
HresOut(const TString& methodName,
        const HRESULT  hres)
{
    THResultId hresID;

    if (!IS_TRUE(hres)) {
        hresID = HRESULT_OMKT_CODE(hres);
        cerr << "Error: \"" << methodName << "\" failed.  "
             << "Returned HRESULT value = " << hresID << "." << endl;
        ::exit(1);
    }
}

Paste the following code for OutputLatin1 into your application:


/////////////////////////////////////////////////////////
// OutputLatin1 outputs a TString containing latin-1
// characters in such a way as to make sure European
// characters print properly.
/////////////////////////////////////////////////////////
static void
OutputLatin1(const TString& OriginalTString) 
{
    TConvertCharset convert("latin1");
    char* ostring = NULL;
    int length = 0;
    convert.FromTString(OriginalTString, &ostring, &length);
    cout << ostring; 
    delete[](ostring);
}