[asterisk-scf-dev] Proposed Naming Conventions

[Kevin P. Fleming]

On 11/29/2011 04:54 PM, Joshua Colp wrote:
> ----- Original Message -----
>> Per https://issues.asterisk.org/jira/browse/ASTSCF-292, I have been
>> tasked with streamlining the naming convention for file, component,
>> and
>> repository names in Asterisk SCF. If you take a look at the issue,
>> then
>> you can see where some of the inconsistencies lie.
>>
>> My proposal is the following:
>>
>> 1. All repository, file, non-component library, and component names
>> will
>> be in UpperCamelCase.
>>
>> 2. All Slice source files, regardless of whether they are defining
>> interfaces or are listing classes, will end with "If".
>>
>> 3. All initialisms and acronyms that are typically written in all
>> uppercase will be formatted as such (e.g. use "RTP" instead of "Rtp"
>> and
>> "PJMEDIA" instead of "PjMedia").
>
> +trillion
>
> It throws me off every time I see this violated right now.
>
>> 4. The C++ source file in each repo that defines the primary Icebox
>> service will be called "Component.cpp". This holds true whether the
>> service is defined as a subclass of AsteriskSCF::Component::Component
>> or the service is defined as a direct subclass of Icebox::Service.
>> Similarly, if the component provides a state replicator, then the name
>> of the source file should be "ComponentStateReplicator.cpp" and the
>> name
>> of the header file should be "ComponentStateReplicator.h".
>>
>> 5. The C++ header and source files that handle configuration of the
>> component over Ice will be called "Configuration.h" and
>> "Configuration.cpp" respectively.
>>
>> 6. Unless there is a compelling reason not to, the primary component
>> provided by a repository will have the same name as the repository.
>> The
>> state replicator should have the same name as the primary component,
>> with "StateReplicator" appended.
>>
>> 7. Where reasonable, a header file containing a primary class
>> declaration should have the same name as the class being declared
>> (i.e.
>> class Foo should be declared in Foo.h).
>>
>> 8. Non-inlined definitions of a class's methods should be in a .cpp
>> file
>> named after the class (i.e. class Foo's methods that are not defined
>> in
>> Foo.h should be defined in Foo.cpp).
>
> Looks good to me.

I am in agreement with these proposed changes as well, although I share 
the concerns previously expressed about the mixing of MixedCase and 
all-uppercase names (especially for repository names). Personally I am 
not aware of any shortage of hyphens or underscores, and the use of them 
does not offend me; and here's an example of where this is a problem:

Right now we have a 'sip' repository. Under this proposal, that would 
become 'SIP'. However, I think that's too ambiguous/broad, and should 
probably (at least) reference the fact that it's built on PJSIP (like 
the RTP endpoint component repository does). Under this proposal, 
though, the resulting repository name would be 'SIPPJSIP'. Either 
'SIP_PJSIP' or 'SIP-PJSIP' are significantly easier to parse.

I can help when the time comes to change the repository names on the server.

As David Lee mentioned, we'll have to ensure that we announce on this 
list when the backhoe is going to cut the fiber cable... I mean, when we 
make the changes and cause all existing clones to either get broken or 
'disconnected' from their parent repos. It might be good to consider 
putting some logic into the gitall script itself to rename local 
repository clones and update their remotes automatically, but given the 
small number of users right now just documenting what needs to be done 
will probably suffice.

I didn't see a proposed list of new repository names; do you have one?

-- 
Kevin P. Fleming
Digium, Inc. | Director of Software Technologies
Jabber: kfleming at digium.com | SIP: kpfleming at digium.com | Skype: kpfleming
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at www.digium.com & www.asterisk.org