Code Conventions

[Bruce MacLeod]

As requested, here are some ideas for coding conventions in the MoTeCH
platform

1) Event Specification :

It would be helpful if the event subject and payload is
specified in a consistent way (package name, fileName, and Event
name). Recent work in the schedule tracking could serve as a pattern.
To start the discussion :

Package : <xyz>.event.constants
Two files : EventDataKey & EventSubject

Content of EventDataKey file should be similar to :

public class EventDataKey {
// EnrolledEntityAlertEvent
public static final String SCHEDULE_NAME = "schedule.name";
public static final String EXTERNAL_ID = "external.id";

// MilestoneEvent
public static final String WINDOW_NAME = "window.name";
public static final String MILESTONE_NAME = "milestone.name";

private EventDataKey() {
}
}

Content of EventSubject should be similar to

public class EventSubject {
private static final String BASE_SUBJECT =
"org.motechproject.scheduletracking.api.";
public static final String ENROLLED_ENTITY_REGULAR_ALERT =
BASE_SUBJECT + "enrolled.entity.regular.alert";
public static final String ENROLLED_ENTITY_MILESTONE_ALERT =
BASE_SUBJECT + "enrolled.entity.milestone.alert";

private EventSubject() {}
}

The above specification may not be sufficient for other modules. In
the message campaign module, there is
MESSAGE_CAMPAIGN_SEND_EVENT_SUBJECT and
MESSAGE_CAMPAIGN_FIRED_EVENT_SUBJECT .
MESSAGE_CAMPAIGN_FIRED_EVENT_SUBJECT is essentially decorating the
MESSAGE_CAMPAIGN_SEND_EVENT_SUBJECT's payload with additional
information. Since we cannot repeat this, it could be indicated with
comments in the EventData class.


2) External (Implementer) packages:

Creating a separation between implementation-required classes and
those that are internal to the module would be clearer for
implementers and promote an easier transition to OSGi. Currently, the
implementer needs to look through all packages to locate
functionality. For example, implementers need to have knowledge about
IVRService, but on top of that they also have to use CallRequest
objects.

3) Consistent naming of Implementer packages :

Given the above, can we develop a naming conventions for the
packages seen by the implementer. ie :
<xyz>.external.domain
<xyz>.external.service
<xyz>.external.exception
<xyz>.external.event.constants
<xyz>.external.controller


4) Module suffix Names : especially API vs non-API:

Can we clarify the meaning of an API module ? Do we have a
consistent implementation Should implementers only need to interact
with API modules? To help clarify this question, when implementing
SMS, using the SMS-api module was sufficient, The sms HTTP module
handled the triggered send event behind the scenes without any
intervention (outside of the JSON definition file). But in other
cases, message campaign for example, implementers need to directly
call its services and the message campaign module does not use api as
part of its name. Nor does the scheduler module, which provides the
scheduler service several modules use. In the case of Voxeo, it was
necessary to make the web app (in particular the dispatcher servlet)
aware of a controller from Voxeo, does this qualify it as an API
module, or is it only when services and classes are directly used by
the implementer?

Are there other suffix conventions we should adopt :
.web ?
.http ?
.ivr.<specific provider ... voxeo or kookoo, ..>
.sms.<specific provider ... voxeo or kookoo, ...>



All the best,
Bruce and Russell