New language extension: Allow underscores in identifiers

Topics related to the use of Oberon language features
Locked
cfbsoftware
Site Admin
Posts: 493
Joined: Fri Dec 31, 2010 12:30 pm
Contact:

New language extension: Allow underscores in identifiers

Post by cfbsoftware » Sat Aug 11, 2012 4:34 am

Release v4.3 of Astrobe will allow the use of the underscore character ('_') in Oberon identifier names (i.e. constant definitions etc.) For example:

Code: Select all

MCU.PINMODEOD0 
can then be written as

Code: Select all

MCU.PINMODE_OD0
This feature is solely intended for use with multi-word uppercase identifiers like these.

Normally you should avoid using uppercase names in Oberon programs to eliminate the possibility of clashing with Oberon's reserved words and standard procedures. However using peripheral register names in your programs that match those used by NXP, STMicroelectronics etc. in their documentation is felt to be a justifiable exception to the rule.

The problem is that the Oberon convention of writing multi-word names in CamelCaps cannot be used for uppercase names. The resulting difficulty of distinguishing each word has a negative impact on legibility. This particularly applies to some of the STMicroelectronics' definitions:

Code: Select all

GPIOCCRH
GPIOCODR
RCCAPB2ENR 
When underscores are allowed these can then be written as:

Code: Select all

GPIOC_CRH
GPIOC_ODR
RCC_APB2ENR

Oberoid
Posts: 18
Joined: Fri Jan 28, 2011 8:57 pm
Location: Amsterdam, Netherlands

Re: New language extension: Allow underscores in identifiers

Post by Oberoid » Wed Jan 23, 2013 2:45 pm

Some considerations about naming register constants.

I'm also wrestling with the uppercase names of registers in datasheets.
PWMMCR cannot be considered "self explaining" - code.

I prefer the camelBack style over the underscore style.

pwmMCR vs PWM_MCR

However the abriviations are still cryptic and I kept going back and forth between code and datasheet.S
My first reflex was adding the NXP description at the declaration part of the register constants. But that did not solve the problem of cryptic abreviations and made the text bulky.
So I used fully written keywords: M becomes Match, C becomes Counter. The keywords Register can be abreviated as R, Interrupt as I, Control as C.

Another optimisation of naming register constants is possible. Using the concept of locality.
Registers of the device pwm are local the module PWM, never accessed directly from other modules.
So from an Oberon perspective using an abreviation of the device in the name of the register is not necessary.

examples naming styles:

NXP
-----------
PWMMIR
PWMMTCR
PWMMPR

camelBack+abr
-------------------
pwmMIR
pwmMTCR
pwmMPCR

camelBack full words
------------------------
pwmMatchInterruptR
pwmMatchTimerControlR
pwmMatchPrescaleControlR

camelBack, full words, no reference
-------------------------------------------
matchInterruptR
matchTimerControlR
matchPrescaleControlR

cfbsoftware
Site Admin
Posts: 493
Joined: Fri Dec 31, 2010 12:30 pm
Contact:

Re: New language extension: Allow underscores in identifiers

Post by cfbsoftware » Thu Jan 24, 2013 7:40 am

These sorts of naming issues are subjective and depend on personal taste. What is important is that you decide on one style and apply it consistently.

When you have decided which you prefer you can then have the best of both worlds by including alias definitions for your constants e.g.:

Code: Select all

CONST
  matchInterruptR  = MCU.PWMMIR;
  matchTimerControlR = MCU.PWMMTCR;
  matchPrescaleControlR = MCU.PWMMPR;
You can then use the naming style you prefer in the body of your code but you have a lookup table at the top of your module which points you to the references in the NXP documentation.

Oberoid
Posts: 18
Joined: Fri Jan 28, 2011 8:57 pm
Location: Amsterdam, Netherlands

Re: New language extension: Allow underscores in identifiers

Post by Oberoid » Fri Jan 25, 2013 10:41 pm

Thanks for your reply
I will try out your recomendations on aliasing constants.

Locked