About nRF SDK naming conventions

RE: About nRF SDK naming conventions

ovrebekk — Thu, 02 Feb 2017 10:18:07 GMT

Thanks for the input Jarmo.

Being a hardware company you are probably correct that many of the drivers are written "from the bottom up" ;) We want the software drivers to be as flexible as possible, and support all the hardware features available, which makes them more complex than needed for many customers.

We do support alternative software stacks, such as mBed or Arduino, if people want more intuitive API's, but the SDK will always be the place to go if you need more flexibility or need to get new features faster.

RE: About nRF SDK naming conventions

Jarmo — Tue, 31 Jan 2017 12:41:48 GMT

Thank you for your answer and the time! I do understand that having consistent rules that do not change when "the game is already running" are important for that kind of large software process.

Well. I am not sure what's actually wrong with the SDK, but everything feels too hard and complicated. Making an application takes two to ten times the time needed to implement same thing with Arduino code. I have written code for nRF5 now over two years, about ten to twenty different kind of customer projects.

After not being able to adopt the thinking behind your SDK, I eventually started to write an extra software layer hiding all that nRF-SDK complexity. For me, it looks like the SDK is written with an approach "we've got a hardware, let's write the software". Instead, what I would look for is to first think what a programmer really needs, and write the API from that point of view.

RE: About nRF SDK naming conventions

ovrebekk — Mon, 30 Jan 2017 15:35:53 GMT

Hi Jarmo

Good function naming is a challenge, and it is very hard to find a set of rules that works great in all circumstances.

When it comes to the use of underscore vs camelcase then underscores is by far the most common in the industry for C code, and is used by standards such as Misra C or K&R. Camel case is more common in object oriented languages such as C++ and Java, and all our Android examples use camel case.

The reason for using abbreviations is to shorten the function names. Our internal guide lines put limits both on the length of function names, and on entire code lines, to avoid having to scroll to the right when reading code. While having long and descriptive names might help to understand that particular function the first time you read it, it will make it harder to get an overview of the code, since you have to break up code lines to avoid them being too long.

We also have a requirement to prefix all function names with the name of the module, which means the module name should be as short as possible to avoid breaking the function name length limit.

As I said in the start all naming conventions have pro's and cons. In the end we try our best to ensure that we are consistent within the Nordic libraries, and that we follow industry standard as much as possible without needlessly reinventing the wheel.

Best regards
Torbjørn

RE: About nRF SDK naming conventions

Jarmo — Fri, 27 Jan 2017 11:11:12 GMT

Yep. As a kid, I might have agreed with you, since I quickly learned all the needed magic words to program ZX-81, VIC-20, Commodore 64, Amiga etc (and actually, also Unix). Nowadays, it is much harder to learn to memorize new programming language details, and I need google a lot. On the other hand, the programming vocabularity is also much higher, today.

RE: About nRF SDK naming conventions

awneil — Fri, 27 Jan 2017 10:27:58 GMT

As you said, I see your point - but don't agree.

RE: About nRF SDK naming conventions

Jarmo — Fri, 27 Jan 2017 10:05:57 GMT

A nice article.

A matter of style, partially yes. If you prefer deep (slow) learning curve then choose abbreviations, but preferring easy starting puts you choose clear wording.

RE: About nRF SDK naming conventions

awneil — Fri, 27 Jan 2017 09:59:32 GMT

You are clearly not a UNIX fan, then!

This is an argument that has been running - and will continue to run - forever amongst software developers & computer scientists.

haacked.com/.../

At the end of the day, it is just a matter of personal style/preference.

RE: About nRF SDK naming conventions

Jarmo — Fri, 27 Jan 2017 09:30:18 GMT

Yes, thank you for your opinions. I see your point but cannot agree.

RE: About nRF SDK naming conventions

awneil — Fri, 27 Jan 2017 09:30:15 GMT

Some people would argue that all those underscores make the name too much work to type, and would prefer

bspBtnBleOnBleEvt()

RE: About nRF SDK naming conventions

awneil — Fri, 27 Jan 2017 09:27:05 GMT

No, I am not employed by nor in any other way affiliated with nor sponsored by Nordic.

after you have worked intensively, say one year, with Nordic's SDK, you get familiar with those acronyms

I don't find any of those abbreviations to be obscure or cryptic:

'ble' is a widespread abbreviation for 'Bluetooth low energy';
'btn' is a common abbreviation, and no major leap from 'button'
etc

You will find similar abbreviations throughout competitors offerings.

which one makes more sense: "btn_ble" or "bluetooth_button_module"

Also ask which one they would rather have to type - 'bsp_btn_ble_on_ble_evt' or 'board_support_package_bluetooth_button_module_bluetooth_event_handler'

"Taking the vowels out" is a common way of "compressing" words in making symbol names in software development in general...

RE: About nRF SDK naming conventions

Jarmo — Fri, 27 Jan 2017 09:15:26 GMT

This is not the first time I am complaining. If you are not Nordic employer, I think continuing is quite fruitless.

Of course, after you have worked intensively, say one year, with Nordic's SDK, you get familiar with those acronyms. But what is the case with all the beginners? For example, try asking some random people which one makes more sense: "btn_ble" or "bluetooth_button_module".

RE: About nRF SDK naming conventions

awneil — Fri, 27 Jan 2017 09:05:50 GMT

It doesn't seem unreasonable to me:

It is part of the Board Support Package - hence the 'bsp' prefix
It is part of the BLE Button Module - hence 'btn_ble'
It is the handler for BLE events; ie, it is called on each BLE event - hence 'on_ble_evt'

Thoroughly descriptive!

So how would you have it named?

developer.nordicsemi.com/.../a01272.html