Open Exchange App ObjectScript Package Manager Naming Convention

Primary tabs

Hi Developers!

Suppose you want to create your ObjectScript library to be distributed via ObjectScript Package Manager. And there is an obvious question: what is the naming convention on the packages and class names?

Naming packages and classnames

There is already some accepted practice with package managers and we will follow the best practices in this field. The most reasonable and simple looks the approach with having company as the first package then project as the second and then classes and subpackages of the project.

The folder structure in this case looks like:

/src/cls/company/project/subpackage/TheClass.cls

and the name of the class is company.project.subpackage.TheClass.cls

and the content of the class is:

class company.project.subpackage.TheClass
{
ClassMethod HelloWorld as %String {
 return "Hello World!"
}
}

If you are not the company but an individual developer, the company package is changed to your surname or nickname whatever you prefer. In my case, the class will look like shvarov.library.demo.Test.cls, and the code:

class shvarov.library.demo.Test.cls
{
ClassMethod Version as %String {
 return "1.0.0"}
}
}

Github profiles, projects, and ObjectScript class names

Ok! What about the libraries which are published on Github?

This naming convention can have a clear reflection of  GitHub repos cause every Github repo has the structure of the company/developer and the project. 

Examples: company's profile and project's repo, and here is developer's profile and one of his repo

But often companies and repos on Github contain hyphens. Hyphens and underscores are not allowed in ObjectScript class names. So in this case developer may introduce a shortcut name for company and project names in ObjectScript classes. E.g. like here in this template project.

Here we have an organisation with name intersystems-community and project with name objectscript-package-template

And developer introduces 'community' to reflect intersystems-community company and 'objectscript' to reflect objectscript-package-template project.

So the class, in this case, looks like:

Class community.objectscript.ClassExample
{
ClassMethod Test() As %Status
{
    set a=42
    return "It works!"
}
}

Same class in the repo

In order to simplify the development of ObjectScript packages please feel free to use the template.

It contains the proper naming for packages and classes and also contains the related module.xml and the dockerfile to make immediate tests with the package.

The dockerfile contains lines that install the ObjectScript Package Manager client (ZPM) so you are able to build and test your new package.

This was described in the following article but will remind you key calls to test any package:

IRISAPP>zpm
IRISAPP:zpm> load /irisdev/app/
.... loads the package
IRISAPP:zpm>package-name package -v
... tests package installation

 

Package names on ObjectScript Package Manager

The structure of module.xml requests you to introduce the name of the ObjectScript package to be used in ObjectScript Package Manager. ZPM supports hyphens in names so the name can be same as you have for the project. E.g. for this particular template ObjectScript module then name will be 'objectscript-package-template', which is stated in 'module.xml' and so could be installed as:

USER:zpm> install objectscript-package-template

So!

This is the proposal for the community on ObjectScript packages naming convention. 

Any ideas on a better approach are very welcome!

 


Replies

I think that the developer should have the freedom to name their classes and packages.
However the name registered in the ZPM should follow a pattern indeed. I'd suggest the lower case with slashes: like-this.

This is the same pattern I use to name my repositories by the way.

Hi Rubens! Thanks for the valuable input.

Yes, freedom is a great thing as soon as nobody harms you upon freedom concepts. What I mean everybody should enjoy the freedom and that's why we perhaps need some community rules to avoid chaos. 

E.g. what if some developer will introduce another module Frontier then Rubens Silva's Frontier?  And if I want these modules to run both in one namespace? 

It's not rocket science, people already have invented naming conventions that's what I'm going to talk and agree about.

Yes, that makes sense, however this would increase drastically the difficulty to write/remember the classe name, that's... unless the keyword Import is used. This way the library user could avoid writing the full package name everytime but... I don't see many using that kind of feature as I noticed that most of the Caché developers prefer to write the full class name whenever they need to call it. So we would need that to become a part of our development habit.

The only exception is any class that belongs to the %LIbrary package. At least from my experience, I never write down %Library.ThePackageIWant, only %ThePackageIWant.

Anyway, the user who downloaded the module would do something like this when using it:

Import org.rfns.Frontier

Class MyAPI.Router Extends Router
{
/// And every other call to any classes from Frontier would omit `org.rfns.Frontier`.
}

Also, I took that naming convention from Java, just to increase the available suggestion.

And I updated the post and added the part on packages names - thanks!