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

[Ken Hunt]

Comments below...
Ken

----- Original Message -----
> From: "Brent Eagles" <beagles at digium.com>
> To: hydra-dev at lists.digium.com
> Sent: Tuesday, June 29, 2010 9:03:42 AM
> Subject: [hydra-dev] Calling for opinions/ideas on interface definition style guidelines
> 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.

More specifically, the intent of the "If" naming was to make it clear to the developer when he or she was dealing with a code-generated file. Many code generating tools (Qt, C# Forms) have some type of naming convention for the files that are generated so that developers know to avoid modifying them by hand. I feel we need to address this in some form. 

There are other suffixes (or prefixes) that might make more since. And there are certainly other techniques for addressing this. For example, the build system's default include paths could "sort of" enforce a directory prefix (ex: #include <slice/name.h>). This isn't quite as heavy handed. But even in this approach, I don't think using the underlying tools name (in this case "slice") is the best idea in the world. (Maybe "api"?) Also, the approach of relying on a directory path isn't as useful for developers in IDEs, where the source file's location would be hardly noticed. 

So I would appreciate a clever idea to address this, other than "let the generated code file names look like any other code". 

> 
> 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. 

> 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.

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. 

We should start a style-guide wiki page, which would be an easier target to comment to than email. It should address both slice definitions and C++ code as a start.

> 
> 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
> 
>