On Wed, May 11, 2011 at 2:57 PM, Michael Dickens
<address@hidden> wrote:
On May 11, 2011, at 4:33 AM, Martin Braun wrote:
> I'll just name some things from the top of my head... [snip] I realise most of these things are very typical for such a large FOSS projects with so many contributors, but still, I can imagine they can confuse other people than me.
For the sake of brevity, I've removed your list -- it's a good list BTW, and yes, quite representative of "a large FOSS projects with so many contributors". Heck, when I look at my internal projects: Once they get large enough it's difficult for me to remember the "desired" APIs & hence they end up having these same issues.
Martin,
I agree, that's not a bad list. And as you know and Michael pointed out, these things to have a way of moving by themselves, even if there is a supposed style structure.
Are they confusing? Yes, sometimes. I've learned with most of the FOSS projects that I work on or use that I cannot assume that the API will be consistent & to make sure to check before using.
Maybe if/when gnuradio-core is split out whoever is doing that work could also review the APIs to make sure they are consistent -- YA API change won't kill GNU Radio, though it might be annoying to end-users.
And, before that, it would be good for Tom (since he's the "benevolent leader") to organize a document describing the desired APIs if there isn't one (I remember having such a discussion with Eric, but I don't know if a "formal" document was ever created) -- examples off the top of my head include:
Yes, I've had a bit of this in the works but probably need to put more emphasis on it.
One quick change in definition/language here. We're not talking about the API, really (some of it is, like the get_ and set_ concept). This is the coding style. The API is actully fairly stable. This has been one of the concept behind our versioning. Anything in the master branch maintains a consistent API. It might not be as consistent between blocks as you might like, but within a block, we don't change the API until we update a version.
So what we really want to discuss is the coding style, which will involve some common concepts of API's into blocks.
Just to point out that another issue with changing API's is that we have a huge base of code, so if we change a style of doing something, it would be nice if we could go back and change everything else to meet the same style. Obviously, we don't necessarily do this.
* underscore_separated_names but never CamelCase;
* separate method names ("get_foo" and "set_foo") instead of method overloading ("foo ()" and "foo (foo_type new_foo)");
* 'b' for bit, 'B' for byte, 'c' for char, 'f' for 32-bit IEEE float, etc...
I agree with points 1 and 2 here. In fact, the Qt Gui work that I inherited is largely in CamelCase (underneath, the GNU Radio interface bits conform to our style) and I've been wanting to change that. But again, it's a lot of code and not enough time to worry about something like that. I have my compulsions for this kind of thing, but they only go so far.
On the third point, we have a problem. 'c' is used for complex numbers, so what do we do about characters? I think we're probably ok with bytes standing in for character almost everywhere, though. We had some discussions with this naming concept in Volk, where I think we've come to a much more verbose but consistent and explicit naming scheme for data types. I think it's a bit much for GNU Radio blocks, though, and it would involve redoing everything.
GRC makes this concept nice, since all ins and outs are color-coded and it will tell you immediately if there is a problem.
That having been said, we need to be a bit better about this. The distinction between bits and bytes is important and confusing (because it's really packed versus unpacked bytes), and unfortunately the 'B' is going to look odd compared to the rest of it. Plus, because its a packed/unpacked, the actual data type is a char regardless.
The other issue is vectors. We use v in the name to indicate that a vector is used, but does that mean the input or output or both? I suppose we want something like _cvcv for both and _cvc for a vector on the input and _ccv for a vector on the output. I don't really like how that looks, but it would work.
I'm sure if you (Martin) wanted to do the legwork organizing such a document, the rest of us would help review and augment it ;) - MLD
We really should put this onto the Wiki. By the way, here's the Volk style page:
Tom