PP9.Programming Style

8/18/2019 PP9.Programming Style

1/27


2/27

Information Hiding

Simplistically Treat different pieces (modules) of code

as black boxes.

The internal details are unknown outsidethe box.

Define an interface to the box

Visible functions

Visible constants and types

Private variables (with rare exceptions)

11/09/2015 EEE20003 Embedded Microcontrollers 2


3/27

Trivial Examples

Charlieplexing code What is necessary to know to use this code

(apart from the wiring)?



4/27

Trivial Examples

ADC code What is necessary to know to use this code

(apart from which channel)?



5/27


C Header Files

Header files provide a poor man’simplementation of an interface to amodule.

It makes public all the accessibleelements of the module.

The internal details of the moduleremain hidden (‘information hiding’).

Much improved if used with C++ butstill may be used to achieveinformation hiding in C.


6/27


Why Use Header Files?

Good style – by creating the header file you are definingthe interface to the module. If done properly you aredeveloping a contract about what the module does. Theinternal details of the module are hidden and may beupdated without breaking other code provided the

interface is unchanged. Consistency checks – C is very poor about matching

function calls parameters and return values betweenfunction calls and the actual function (much improved inC++). There are default rules if none are explicitly given.

This is a significant problem if the default rules areinappropriate! Use of header files provide a consistencycheck between function use and declaration (see laterexample).


7/27


Header File Example

ADC.c

Definitions of public functionsDefinitions of public variablesDefinitions of private constantsDefinitions of private functions

Definitions of private variables

ADC.h

Declarations of public functionsDeclarations of public variables (to be avoided where possible!)Definitions of public constants, types etc (#defines, enums etc.)

main.c

Use of public functionsUse of public variablesUse of public constants

Public means to be available for use by other modulesPrivate means for use within the module onlyDeclaration means saying the thing exists but isn’t hereDefinition means creating the thing itself

#include#include


8/27


9/27


C Header Files

No Code in Header Files (Unlike C++ where you may have

inline member functions, constructors

etc.)


10/27


Use of #define

if ((PORT & 0x02) != 0)

PORT |= 0x20;

else

PORT &= 0xDF;

#define LED (1


11/27


#define

Using #define improves the readability ofthe code as well as making it less likely thatyou will make simple errors. You mayconfuse 0x02 with 0x20 but are unlikely toconfuse

LEDwith

SWITCH.

It also improves the maintenance of thecode. For example, if the hardware ischanged when developing the PCB layout,

say the LED is moved to pin 0, then onlyone line of code needs to be changed:#define LED (1


12/27


13/27


#define Once only

If some constant is dependent upon anotherconstant then derive it – Don’t defineindependently which creates maintenanceproblems. Example

// Port T Masks#define LEFT_LED (1


14/27


Constant Expressions

It doesn’t matter (within reason!) howcomplicated a constant expression is. Itdoes not affect the runtime program sincethe expression is evaluated by the compiler

and replaced by a simple constant. It justrepresents extra work for the compiler andusually less work for the programmer.

So – there is no reason for getting yourcalculator out when writing a program!


15/27


Self scaling code #1

Add a value to the array. Whatmaintenance issues are there? Fix them.

int ar[4] = {10,56,29,18}; // Array of heights

...

for (sub=0; sub


16/27


Self scaling code #2

What maintenance issues are there?int ar[4] = {10,56,29,18}; // Array of heights...

for (sub=0; sub


17/27


C Style

Indent properly Use mixed-case starting with lowercase

for variable names (camelCase) emergencySwitch

Use uppercase for #define constants – this is a pain but it’s the acceptedstandard. EMERGENCY_SWITCH

Use a fixed-width font for printing code.

Indent properly!


18/27


Meaningful Names

Use meaningful names for functions,variables and symbols: initLCD(), checkInputs()

currentNote,

MAX_RETRIES Avoid:

i, tla’s and cryptic abbreviations.

vague names (count – what is being counted!)

stupid symbols (#define BIT0 etc.) Some exceptions:

There are accepted names for hardware registersand the bits within them e.g. PDDR, PDIR etc.


19/27


Commenting

Strategic commenting! Not every line needs a comment.

Comment pieces of code that work as a

unit. Use an empty line to separate the pieces.

GPIOC->PDDR |= STOPLIGHT|EMERGENCYLIGHT; // set port outputs

// Set motor to speed 10

GPIOC->PSOR = MOTOR_ON;

GPIOA->PDOR = (GPIOA->PDOR &~MOTOR_MASK)|MOTOR_VALUE(10);

...


20/27


Commenting

Place your comments so they are easilyread:

Spaced apart at end of line.

As a mini-banner line before a block.;************************; Main search loop;loop:

cmp r0,r3 ; compare memory to search key

beq foundIt ; found it–exit loop

add r0,r0,#1 ; point to next locationcmp #0x2000 ; at end of range?bls loop ; no – back for more


21/27


Commenting

Every function should have a banner! Description (in English!) of what the

function does – not how it does it.

Input conditions – what it expects toreceive as parameters and preconditions.

Outputs – how it changes any referenceparameters. Any other affects it has.


22/27

Commenting


/**

* Turn on the given LED

*

* @param ledNum LED to turn on (0..6)*

* @note 0 => All LEDs off

*/

void setLED(int ledNum) {...

}


23/27


Commenting

Comments should indicate the purposeof the code not repeat the code inEnglish.

Avoid stupid comments if (z>0)... // check if z is

// greater than 0

i = 0; // Set i to 0

The above is the jackpot – It will attractnegative marks for both stupid namesand stupid comments!


24/27


Classic Errors

Initialise EVERYTHING (esp. portdirection, port value).

Zero is a value – don't assume it

defaults by magic! Ports, registers, etc may be shared –

use bit manipulation where needed.

Inputs may change – input skew – takesnapshots of a port if the relationshipbetween bits is important.


25/27


#define Errors

#define size (23);

if (x > size) {...

if (x > (23);) {...

Syntax errormessage here

Error here.

but…


26/27


#define Errors

#define width 3+56

i = 2 * width;

i = 2 * 3+56;


27/27

Documents

PP9.Programming Style