Coding Guidelines in webMethods IS – Part I

Hello everybody and welcome back to wm-explorer. This post intends to be the start of a series on how to write good, easy to read, maintainable, performant (FLOW) code in webMethods Integration Server.

 

For those of you who liked the web services discussions we had in the last 2 posts (here and here), don’t worry. The web services topics will come back to wm-explorer soon. We really cannot have too many discussions on what seems to be the preferred integration mean between applications.

 

It’s the start of the year and this brings back in my mind different starts: of a project, of a task, of working with webMethods IS. And like in every start, a reasonable amount of work has to be invested in setup.

 

People starting with webMethods IS can include this series of posts in their setup as it aims to help them reach the next level faster and less painful.

In the interest of full disclosure, the series is based on my experience and my years working with webMethods IS. It is not endorsed by SoftwareAG, although I hope they like what is written here.

 

OK, so before we get started, let’s ask ourselves if there is really the need for Coding Guidelines in Integration Server? I, for one, think there is. My reasons are the following:

  • there is no comprehensive guide on this topic from SAG*
  • people think that FLOW language is easy and no guide is needed**
  • it is easier for everybody is guidelines are followed (especially for those that end up maintaining your code)

 

*I am sure they have something in regards to this in their PRIME methodology and tool offerings but that information is not available, as far as I know, for anyone just starting with webMethods.

**Blindly starting coding, even in the easiest languages, is not recommended. It might be suited for exercises, proof of concepts and getting to know the language but it will certainly not fly when you write productive code. Going on this path leads to bad programming and making some nasty mistakes that will make your code harder to read and maintain, not to say error-prone.

 

The moment has arrived to dive into the first part of the guidelines: Naming Conventions.

 

Naming conventions

 

We will deal here with the rules for naming the IS artifacts (packages, folders, services, etc..).

There are some general rules that apply, so I will mention them just once:

  • English should be the standard language for naming
  • names should contain only alpha-numeric characters

 

Please note that all the rules are valid for the cases where the developer has the control over the creation of the artifacts. For the cases where the code is generated (web service descriptors, REST endpoint services), it is better to leave the names as they were generated.

Why? Because changing generated code is never a good idea. It involves a large amount of work that will be lost anyway when the code is regenerated.

 

Package naming conventions

Package structure

 

Below you can find an example of how the folders within the package should look like (seen from the Service Development view):

  • cached – contains cached services
  • doc – contains the document types defined for this package
  • init – contains the startup services (startup is also a good name for this folder)
  • pub – contains the public API of the package, i.e the services that are used by other packages
  • pub/scheduler – contains scheduled services; in this way, it is easy to identify them
  • service – contains only adapter services
  • shutdown – contains shutdown services
  • util – contains utility services that are used only from this package; if the service needs to be used by other packages as well it should be moved to a common services package
  • ws/provider – contains Web Service Providers and the related artifacts
  • ws/consumer –  contains Web Service Consumers and the related artifacts

 

Of course, the list above is not final nor exhaustive. If it makes sense you can add more folders. You might want to add a folder that holds the REST resources. It can be named rs or resources.

You might also want to remove some folders from what I have presented above if they are not used. There is no added value in keeping empty folders.

 

A package should contain services and other artifacts that belong together. It is wise to keep the ratio of interfaces/package low. This is important for deployment purposes because if one interface changes you will need to deploy the whole package (i.e all the interfaces).

 

Package name

 

Please follow the below rules for naming the packages:

  • The package name should not contain the word Package or abbreviations of this word. It is clear that it is a package. Do not overkill.
  • The package name should be camel case, starting with an uppercase character. Can contain underscore if really, really needed.
  • Packages that hold connections or document definitions can be named accordingly. This means they can have the suffix Connection, respectively, Document.
  • It is OK to prefix the package name with a prefix that identifies the organization that owns the package.
  • Packages should not start with Wm because this usually identifies packages from the standard webMethods distribution (ex: WmPublic).
  • Packages that contain tests or non-productive artifacts can be suffixed with something like _TEST and must not be deployed to the Production environments.

 

Root folder name

 

On this topic, I have seen two major ways of naming the root folder (i.e the folder just below the package).

  • Root folder has the same name as the package

People who like this usage claim that it is easy to identify a certain service or asset within a package. If you have the fully qualified service name you can easily navigate to it without the need to search.

  • Using the Java-like naming convention

In this case, you use a prefix folder structure across all packages in the IS. This structure should have maximum 2 levels of depth and should be the inverse domain name of the organization.

Example:
Your organization: Mystery Inc. (you saw Scooby-Doo, right?)
Your organization site: www.mystery.com (I hope this is not some sort of shady site)
Root folder structures: com.mystery.accounting, com.mystery.invoicing

 

I prefer the second option because it resembles best with the standard of other languages (ex: Java) and because it eases refactoring. By using this option there will be no namespace issues when moving code from one package to another.

So my recommendation would be to go with the Java-like naming convention. In this way, you will have the same folder prefix for all the packages in your IS and you will differentiate below this prefix.

You can check below how the rules look like for the specified example.

 

Other naming conventions

 

Folder names should have a clear name that reflects their content and should contain only lowercase letters. (The underscore character is accepted, but should be avoided).

Service names must be camel case and start with lowercase letters (just like standard Java methods). Exception: the REST resources which are generated (_get, _post, _put, _delete, etc.) and should not be changed.

Variable names must be camel case and start with a lowercase letter. This is valid for variable names in both document types and service signatures. Also, document reference variables should follow this rule.

Document type names must be camel case and start with an uppercase letter. The document types in IS are similar to JAVA POJO’s, so they should respect the same rules. Also, use underscore only if you must.

 

You know what, do no use underscore. Name the assets in such a way that using underscore is not needed. This rule will help you in the namings and will certainly help me because I had planned to repeat it a lot in this section.

 

Flat file names must be camel case and start with an uppercase letter. Same goes for schema names and connection names. For the latter, if you have multiple connections it is a good idea to suffix the name with _NTX, _LTX, and _XA.

Adapter names must be camel case and start with a lowercase letter. Same goes for trigger names and web service descriptors.

 

Now I do realize that IS has more asset types that are presented here. I listed the most frequently used. If you have problems naming other artifacts you can ask yourself 2 questions: “How are such artifacts named in other programming languages?” and “What would be a suitable naming convention based on what I know so far?”.

 

To be honest, if you consider the naming conventions to be the boring part of any Coding Guidelines, I do not blame you. It is not the most dynamic part of the guidelines.

That’s why I want to offer you a Thank you! for sticking with me until this point.

Next posts we will dive deeper into some general, as well as specific (performance, security) topics and things will get spicier and more animated.

 

See you next time,
Tury

 

2 thoughts on “Coding Guidelines in webMethods IS – Part I

  • Hi,

    In the project I’m in, we are starting with these rules:

    1. Language
    The language choices are meant to facilitate communication, even when actions are years apart.
    [LNG.1] MUST use English to name all programmatic identifiers.
    [LNG.2] MUST use English to write code documentation, using well-formed sentences and full words.
    [LNG.3] SHOULD define uncommon terms and acronyms in the glossary of the technical design documentation.

    1.1. Word Choice
    [WRD.1] MUST NOT use any Java reserved word (package, class, static, etc.) [see Java references]
    [WRD.2] MUST use ONLY alphanumeric characters
    [WRD.3] MUST NOT use a numeric character as the first character
    [WRD.4] MUST NOT use punctuation characters in the names
    [WRD.5] MUST name an identifier according to its meaning
    [WRD.6] MUST NOT use the type in its name
    [WRD.7] MUST NOT include environment related information
    Code Examples
    [WRD.6] Wrong:”connectionString” –> Correct:”connectionName”
    [WRD.7] Wrong:”connectionNamePROD” –> Correct:”connectionName”

    1.2. Abbreviations
    [ABR.1] All abbreviations MUST be defined in the glossary of the technical design documentation.
    [ABR.2] MUST NOT use abbreviations or contractions as parts of identifier names.
    [ABR.3] MUST NOT use acronyms that are not generally accepted in the computing field
    [ABR.4] SHOULD use well-known acronyms to replace lengthy phrase names

    1.3. Case Sensitivity
    The webMethods platform is case-sensitive. Improper casing can lead to difficult to troubleshoot bugs.

    You MUST follow ONLY ONE of the following capitalization rules below.
    [CAP.1] Camel case: the first letter of an identifier is lowercase and the first letter of each subsequent concatenated word is
    capitalized (also called lower camel case or LCC).
    [CAP.2] Pascal case: the first letter in the identifier and the first letter of each subsequent concatenated word are capitalized
    (also called upper camel case or UCC).
    [CAP.3] Uppercase: all letters in the identifier are capitalized.
    [CAP.4] Compound names MUST follow rule [CAP.1].

    For compatibility with Java standards, CAP.1 SHOULD be used when developing in webMethods Integration Server

    Package and namespace organization and naming is another story… (on a future post).

    Disclaimer: I’m working with Ferrologic in a automatic code validation tool to enforce these rules.

    • Hi Gerardo,

      I see a very detailed and formalized list which is a good thing. An equally good thing is that there are many common topics/rules between our lists.
      Feel free to post comments on any topic on this blog. I plan to write 1-2 more posts in this series.

      Also for code validation tool, do you happen to have some sort of a white paper on it?
      I am planning to list and talk about in a future post about the available tools for code validation/coding guidelines. I can add your tool as well if I know more about it.

      If not let me know when it is publicly available as I would like to check it out.

      Tury

Leave a Reply

Your email address will not be published. Required fields are marked *