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

[Brent Eagles]

Hi,

Writing interface definitions as part of the design process is the most direct way to document ideas and decisions about a component's external interface. It would be a good idea to settle on some stylistic guidelines before too many are written. I'll start the discussion off with a few points that I've recently raised:

1. File names: there has been at least one vote for an "If" suffix for the name part of the filename (e.g. SomeInterfaceIf.ice). The point of adding the "If" is that C++ files generated from that Slice definition will also have the "If" as part of their name (e.g. SomeInterfaceIf.h and SomeInterfaceIf.cpp) making it clear that these files contain interfaces.

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.

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.

4. Comment-to-documentation processing and how doc comments are formatted: self-explanatory. Doxygen seems a natural choice here, but that leaves the details of the comments themselves open. 

5. Versioning: an approach has documented here https://myth.asterisk.org/wiki/download/attachments/1212445/Versioning.pdf and modifications have been made to Ice to support it. Starting on the right foot here could save us a lot of headaches down the road.

That's all I have at the moment. I'm sure there are some other details that need clarification.

Cheers,

Brent

---
Brent Eagles
Digium, Inc  |  Software Developer
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at: www.digium.com & www.asterisk.org