[hydra-dev] Calling for opinions/ideas on interface definition style guidelines

[Kevin P. Fleming]

On 06/30/2010 08:41 AM, Brent Eagles wrote:
> ----- Original Message -----
>> Comments below...
>> Ken
>>>
>>> 2. Formatting: I expect that the majority would assume that the
>>> asterisk formatting style is the way to go. Its not that common for
>>> other C++/Java like languages, but it is just an IDL file.
>>>
>> Well, we're developing much more than IDL, and the generated code will
>> have a big impact on the style of the non-generated code. I don't
>> think using C-style conventions makes much sense at all.
> 
> Indeed. In this case, I was only referring to things such as "curly brace on same line/new line" types of choices which would not affect the generated code.

For code layout, we should use whatever we are comfortable with in each
language... since there really aren't many rational reasons why one
layout is better than another (except the hideous examples we've all
seen), for most of us coming from Asterisk-land formatting the C++ code
in a similar fashion to what we use in Asterisk would be most logical
choice. However, that doesn't need to affect any C# or Java code we
write (although the same formatting could be used), if that would result
in C# or Java code that is very different from what most developers in
those languages are used to seeing.

> 
>>
>>> 3. Identifier names: AFAIK, this hasn't been discussed at all.
>>> Considering the reaction to the Ice 3.4.1 translators supporting
>>> underscores in identifiers, I suspect there is some intent to use
>>> underscores. Regardless, Slice is language agnostic and C/C++ is
>>> pretty much the only language community where underscores are
>>> pervasive so there may be some room for discussion. There are
>>> countless "variations on themes" here, but here are few to start:
>>>
>>> - MS/Borland like: nearly everything except variables/arguments are
>>> camelBack starting with upper case. Arguments are camelBack starting
>>> with lower case characters (variation: EveryThing is CamelBack with
>>> UpperCase as the First Letter).
>>>
>>> - Java like: (this is pretty much what ZeroC uses for its Slice
>>> definitions) Types and scopes are CamelBack (upcase first letter)
>>> and
>>> methods are arguments are camelBack (lower case first letter).
>>>
>>> - Underscore land: a generalization here might be the Asterisk
>>> guidelines.
>>>
>>> - Boost-ish: I'm not sure but I think this is basically like
>>> underscore land with things like template parameters starting with a
>>> capital letter. However, their naming rationale is driven by the
>>> possibility of elements of the boost library being included in the
>>> STL
>>> in the future. This rationale doesn't really apply, but I included
>>> boost here anyways because it will most likely be used at some point
>>> in implementing components.
>>>
>>> Remember, identifier names are directly translated to the target
>>> language. Unlike formatting style, this decision has direct impact
>>> on
>>> how things look in the implementation language. We need to consider
>>> what it will look like to have Java file names like
>>> bridging_factory.java and code like bridgePrx =
>>> bridge_factoryPrx.create_bridge() and some_other_object.toString();
>>> As
>>> it happens, there is no way to universally avoid such oddities (e.g.
>>> NET uses CamelBack where Java uses camelBack). A middle-of-the-road
>>> convention can make things a *little* nicer though.
>>>
> 
> < snip >
> 
>> You didn't state your own preference! The style you labeled MS/Borland
>> (UpperCamelCase, with lowerCamelCase for variables) is used by much
>> more than just MS/Borland. I would say it's the most common C++ coding
>> style, and seems suitable. I like the Java convention just fine when
>> I'm working in Java. But the slice definitions need to choose one or
>> the other, and I'd be happy with either approach. Since we're doing
>> mostly C++ for the core, I'd think we'd adopt a C++ convention.
> 
> I *had* included my personal preference in earlier drafts but felt that as the provocateur in this case it would be heavy handed to include it in the initial volley :) Basically, I'm a java-style kind-of-guy. I could come up with all kinds of rationalizations.. but honestly I think the reason I have this preference is because it is closer to what I've always done. The OMG IDL style guidelines uses CamelCase for everything but members (operations, attributes) etc. which use underscores and constants which are upcased and underscored. ZeroC did the "java-style" type of thing... maybe just to be different than the OMG, but probably more likely because it started with a project that used C++ with the Qt framework and Java (which are very similar).
> 
> Reminiscing brings up something that seemed like a quirky benefit of the OMG style. OOC always used Java-style naming conventions when implementing code. You could sometimes tell if a method was something defined in IDL because it had a different naming style. However, that *does* seem like a "look on the bright side" kind of rationalization :) 
>  

I was originally in the 'underscore' camp, but now that I've seen
Brent's examples of what that will result in for generated code in C#
and Java, I can see why it would not be a good choice. There is also the
incredibly tiny issue that it makes longer type and identifier names,
which would increase overhead of Ice operations on the wire a bit :-)

So... my suggestion is to use the style that ZeroC uses, since it seems
fairly acceptable in all three major languages.

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