Regeln für das. Schreiben von C Code

Transkript

1 Regeln für das Schreiben von C Code Prof. Dr.-Ing. Otto Parzhuber Fachhochschule München Fachbereich Feinwerk- und Mikrotechnik Labor für Datentechnik Datei:c_coding.doc Seite 1

2 1.0 Einführung Die folgenden Kapitel befassen sich mit meist sehr einfachen Regeln, deren Einhaltung die Qualität eines Programms aber deutlich verbessern kann. Als Grundlage diente der Artikel C-Coding Standard von Jean Labrosse ( Feste Regeln oder Programmierkonventionen sollten in einem Softwareprojekt bereits in einem frühen Projektstadium eingeführt werden. Nur so ist es möglich, im ganzen Projekt Konsistenz zu erreichen und eine vernünftige Projektverwaltung zu gewährleisten. Jeder Programmierer entwickelt im Lauf der Zeit seinen eigenen Programmierstil. Ob dieser gut oder schlecht ist kann er selber überprüfen, wenn er sich die folgenden Fragen stellt. Wenn der Code portabel, konsistent, schnörkellos, einfach zu warten, verständlich, einfach ist, erfüllt er die hauptsächlichen Anforderungen an einen guten Code. 2.0 Prinzipien Der grundlegende Gedanke dieser Standards kann mit Wartbarkeit eines Codes kurz beschrieben werden. Dies bedeutet, dass Code lesbar, verständlich, testbar und portabel ist. Der gesamte Code muss im Standard ANSI C geschrieben sein. Das bedeutet, dass die Funktionsprototypen in ANSI C und deshalb auch die Typdefinitionen innerhalb der Klammern stehen müssen. Der Code muss einfach gehalten werden. Verwenden Sie nur explizite Vereinbarungen. Vermeiden Sie implizite oder unklare Eigneschaften der Sprache. Drücken Sie sich klar aus. Programmieren Sie durchgängig. Benützen Sie die gleichen Regeln so oft wie möglich. Halten Sie sich an die Standards. Wenn Sie Code schreiben müssen, für dessen Lösung kein direkter Standard existiert, versuchen Sie so nah am Standard zu bleiben wie möglich.(spirit of Standard) Vermeiden Sie komplizierte Anweisungen. Anweisungen, die viele Abfragen und Entscheidungen enthalten sind schwer zu lesen und noch schwerer zu testen. Vermeide GOTO. Spaghetticode vermeiden. Datei:c_coding.doc Seite 2

3 Aktualisieren Sie alten Code. Wenn Sie alten Code auf neuen Stand bringen, nützen Sie die Gelegenheit und wenden die hier beschriebenen Regeln an. Damit stellen Sie sicher, dass über die Zeit auch ihr alter Code den geforderten Kriterien entspricht. Die Gefahr, dass der Code irgendwann im Papierkorb verschwindet verringert sich ungemein. 3.0 Quelldateien Zeilenbreite Im komprimierten Mode können bis zu 132 Zeichen auf eine Zeile gedruckt werden, das sollte ruhig ausgenützt werden. Die Begrenzung auf 80 Zeichen war früher wegen den Monitoren notwendig, die nur 80 Zeichen darstellen konnten Benutzen des TAB Zeichens TAB characters (ASCII character 0x09) DÜRFEN NICHT benutzt werden. Das einrücken MUSS mit dem Leerzeichen (space character ASCII 0x20) erfolgen. Die Anzahl der Spalten, die mit dem TAB Zeichen eingerückt werden ist nicht gleich, sondern hängt vom verwendetem Computer oder Drucker ab. Es muss um 4 Zeichen eingerückt werden. Es werden also 4 Leerzeichen (space character) benutzt. Ausnahme sind die case-anweisungen, hier wird um 5 Zeichen eingerückt (siehe auch Kapitel ->Konstrukte). Verwenden Sie einen Dateikopf. Schreiben Sie am am Anfang jeder Datei einen Dateikopf mit Firma, Adresse, Copyright, Programmierer, Beschreibung der Datei, etc: /* * Micrium, Inc. * 949 Crestview Circle * Weston, FL * * (c) Copyright 2000, Micrium, Inc., Weston, FL * * All rights reserved. Micrium's source code is an unpublished work and the * use of a copyright notice does not imply otherwise. This source code contains * confidential, trade secret material of Micrium, Inc. Any attempt or participation * in deciphering, decoding, reverse engineering or in any way altering the source * code is strictly prohibited, unless the prior written consent of Micrium, Inc. * is obtained. * * Filename : * Programmer(s): Joe Programmer (JP) * John Doe (JD) * Created : YYYY/MM/DD * Description : */ Eine Implementierungs-Datei ist eine Datei, die ausführbaren Code enthält, im Gegensatz zu einer Header-Datei, die keinen ausführbaren Code enthält. Das Layout beider Dateitypen sollte in derselben Form gestaltet sein. Leere Abschnitte können weggelassen werden, wenn ein Abschnitt jedoch existiert, muss er in der folgenden Reihenfolge in der Datei stehen: Datei:c_coding.doc Seite 3

4 Implementation File Layout: File heading Revision history #include #define constants Macros Local data types Local variables Local tables Local function prototypes Global functions Local functions Header File Layout: File heading Revision history #define constants Global macros Global data types Global variables Externals Global function prototypes Trennen Sie Hauptabschnitte des Codes. Jedem Abschnitt des Codes sollte ein Kommentarblock wie unten gezeigt vorangestellt werden /* * DATA TYPES */ typedef unsigned char BOOLEAN; /* * PROTOTYPES */ BOOLEAN OSIsTaskRdy(void); Header-Dateien müssen vor einem versehentlichen mehrfachen Einbinden durch Prüfen der Definition einer Variablen geschützt werden. Anmerkung: Die Direktive!defined(X) sollte #ifndef X vorgezogen werden. #if!defined(module_h) #define module_h Body of the header file. #endif /* End of module_h */ Datei:c_coding.doc Seite 4

5 4.0 Kommentare Besser kein Kommentar als ein sinnloser oder falscher (Make every comment count). Code und Kommentare müssen deutlich sichtbar getrennt sein. Minimiere Kommentare, die in Anweisungen eingebettet sind! Beginne NIEMALS einen Kommentar unmittelbar über dem Code wie unten gezeigt. Der Code wird dadurch schwierig lesbar, da die Kommentare das schnelle visuelle abscannen des Codes stören.. void ClkUpdateTime (void) /* DO NOT comment like this! */ /* Update the seconds */ if (ClkSec >= CLK_MAX_SEC) ClkSec = 0; /* Update the minutes */ if (ClkMin >= CLK_MAX_MIN) ClkMin = 0; /* Update the hours */ if (ClkHour >= CLK_MAX_HOURS) Clkhour = 0; else ClkHour++; else ClkMin++; else ClkSec++; Beenden Sie einen Kommentar über mehrere Zeilen niemals nur mit einem Kommentarabschlusszeichen. NIEMALS einen Kommentar so schreiben wie in dem folgenden Beispiel: /* This type of comment can lead to confusion especially when describing a function like ClkUpdateTime (). The function looks like actual code! */ Verwenden Sie Kommentarblöcke zum abtrennen von verschiedenen Codeblöcken. Unten ist ein Kommentarblock gezeigt. Beachten Sie, dass der Kommentarblock zentriert und in GROSSBUCHSTABEN geschrieben ist. /* * VARIABLES ******************************************************************************* */ Datei:c_coding.doc Seite 5

6 Verwenden Sie so oft wie möglich Kommentare, die in derselben Zeile dem Code nachfolgen. Beginnen Sie einen Kommentar so oft wie möglich in derselben Zeile wie der Code, direkt nach dem Code. Wenn Sie den Kommentar untereinander ausrichten, erleichtern Sie die Lesbarkeit des Codes. void ClkUpdateTime (void) if (ClkSec >= CLK_MAX_SEC) /* Update the seconds */ ClkSec = 0; if (ClkMin >= CLK_MAX_MIN) /* Update the minutes */ ClkMin = 0; if (ClkHour >= CLK_MAX_HOURS) /* Update the hours */ ClkHour = 0; else ClkHour++; else ClkMin++; else ClkSec++; Verwenden Sie #if 0 und #endif für das auskommentieren von Codeblöcken. Kommentare dürfen nie geschachtelt werden. Benutzen Sie stattdessen besser die Direktiven #if 0 and #endif für das auskommentieren von größeren Teilen eines Programms. #if 0 /* Comments out the following code */ #define DISP_TBL_SIZE 5 /* Size of display buffer table */ #define DISP_MAX_X 80 /* Max. number of characters in X axis */ #define DISP_MAX_Y 25 /* Max. number of characters in Y axis */ #define DISP_MASK 0x5F #endif 5.0 Vereinbarung für Namen Generelle Vereinbarungen: #define constants: #define macros: typedefs: enum tags: All upper case characters Words separated by an underscore (i.e. `_') Examples: DISP_BUF_SIZE, MIN(), MAX(), etc. Local variables (i.e. function scope): All lower case Words separated by an underscore (i.e. `_') Use standard names (e.g. i, j, k for loop counters, p for pointers etc.) File scope variables: Prefixed with the module name followed by an underscore (i.e. `_'). Datei:c_coding.doc Seite 6

7 Names separating words start with an initial capital. Declared static. Examples: Disp_Buf[], Comm_Ch, etc. Global variables: Prefixed with the module name. Names separating words start with an initial capital. Examples: DispMapTbl[], CommErrCtr, etc. Local functions: Prefixed with the module name followed by an underscore (i.e. `_'). Names separating words start with an initial capital. Declared static. Example: static void Comm_PutChar() Global functions: Prefixed with the module name. Names separating words start with an initial capital. Example: void CommInit() Trenne verschiedene Wörter mit einem vorangestellten Großbuchstaben (e.g. DispBuf[]). Namen in einem alten Code, der nur Kleinbuchstaben besitzt, MÜSSEN mit einem underscore character getrennt werden ( '_', ASCII character 0x2D). Benutzen Sie durchgängig Akronyme, Abkürzungen und Mnemonics. Legen Sie eine Standardbibliothek für Akronyme, Abkürzungen und Mnemonics an, die von allen Programmierern benutzt werden muss. Die gezeigte Liste erhebt natürlich keinen Anspruch auf Vollständigkeit. Für das Programmieren ist diese Liste, sortiert nach Akronym, Abkürzung oder Mnemonic hilfreich. Benutzen Sie für Namen das Format 'Modul-Objekt-Operation' mit den Akronymen, Abkürzungen und Mnemonics. Halten Sie sich an die folgende Regel, wenn Sie eine globale Konstante erzeugen: Am Anfang steht der Name des Moduls, dann folgt der Name des Objekts, und schließlich der Name der Operation. OSSemPost() OSSemPend() etc. Bibliothek für Akronyme, Abkürzungen und Mnemonics (AAM) Beschreibung Akronym, Abkürzung, oder Mnemonic Argument Arg Buffer Buf Clear Clr Clock Clk Compare Cmp Configuration Cfg Context Ctx Delay Dly Device Dev Datei:c_coding.doc Seite 7

8 Disable Display Enable Error Function Hexadecimal High Task I/O System Initialize Mailbox Manager Manual Maximum Message Minimum Multiplex Operating System Overflow Parameter Pointer Previous Priority Read Ready Register Schedule Semaphore Stack Synchronize Timer Trigger Write Dis Disp En Err Fnct Hex Priority HPT IOS Init Mbox Mgr Man Max Msg Min Mux OS Ovf Param Ptr Prev Prio Rd Rdy Reg Sched Sem Stk Sync Tmr Trig Wr Benutzen Sie IMMER diese Standard Akronyme, Abkürzungen und Mnemonics. Benutzen Sie die Standard Akronyme., Abkürzungen und Mnemonics auch dann, wenn Sie das komplette Wort schreiben könnten. Zum Beispiel, benützen Sie IMMER Init anstelle von Initialize! Datei:c_coding.doc Seite 8

9 6.0 Datentypen Alle Datentypen MÜSSEN mit Großbuchstaben deklariert werden. Wörter werden mit dem underscore character abgetrennt (i.e. '_', ASCII character 0x2D). Verwenden Sie die folgenden portablen Datentypen. Alle Stanardtypen in C (ausgenommen char ) MÜSSEN vermieden werden, da ihre Größe nicht portabel ist. Deklarieren Sie stattdessen folgende Datentypen (INT?? und FP??), die vom verwendeten Prozessor und Compiler abhängen. typedef unsigned char BOOLEAN; /* Logical data type (TRUE or FALSE) */ typedef unsigned char INT8U; /* Unsigned 8 bit value */ typedef signed char INT8S; /* Signed 8 bit value */ typedef unsigned short INT16U; /* Unsigned 16 bit value */ typedef signed short INT16S; /* Signed 16 bit value */ typedef signed short INT32U; /* Unsigned 32 bit value */ typedef signed short INT32S; /* Signed 32 bit value */ typedef signed short INT64U; /* Unsigned 64 bit value (if available)*/ typedef signed short INT64S; /* Signed 64 bit value (if available)*/ typedef float FP32; /* 32 bit, single prec. floating-point */ typedef double FP64; /* 64 bit, double prec. floating-point */ Die Standardtypen Struktur und Union MÜSSEN mit typedef ersetzt werden. Alle Strukturen und Unionen MÜSSEN wie unten gezeigt mit typedef ersetzt werden. Genauso wichtig ist es, diese Datentypen ausschließlich mit GROSSBUCHSTABEN zu schreiben. Im Zusammenhang wird es offensichtlich, dass alle großgeschriebenen Buchstaben vor einer Variablen oder Funktion bedeuten: dies ist ein Datentyp und keine Konstante oder Makro.. typedef struct char RxBuf[COMM_RX_SIZE]; /* Storage of characters received */ char *RxInPtr; /* Pointer to next free loc. in buffer */ char *RxOutPtr; /* Pointer to next char. to extract */ INT16U RxCtr; /* Number of characters in Rx buffer */ char TxBuf[COMM_TX_SIZE]; /* Storage for characters to send */ char *TxInPtr; /* Pointer to next free loc. in Tx Buf */ char *TxOutPtr; /* Pointer to next char to send */ INT16U TxCtr; /* Number of characters left to send */ COMM_BUF; Ausrichten der Struktur. Die Datentypen jedes Strukturmitglieds werden um 4 Zeichen eingerückt und die Namen der Strukturmitglieder sind untereinander ausgerichtet. Achten Sie darauf, auch die Kommentare untereinander auszurichten. Gültigkeit des Datentyps. Wenn ein Datentyp nur innerhalb der Implementierungsdatei genutzt wird, MUSS dieser innerhalb der Implementierungsdatei deklariert sein. Wenn der Datentyp global ist, MUSS die Deklaration in der Headerdatei des Moduls stehen. Datei:c_coding.doc Seite 9

10 7.0 Layout Schreiben Sie nur eine Anweisung in jeder Zeile des Codes : DispSegTblIx = 0; DispDigMsk = 0x80; Anstelle von: DispSegTblIx = 0; DispDigMsk = 0x80; Trenne zusammenhängende Codeblöcke durch leere Zeilen oder Kommentare. Schreiben Sie die folgenden Operatoren OHNE Freizeichen : -> Struktur Pointer Operator p->member. Struktur Mitglied Operator s.member [] Array index a[i] Klammern nach Funktionsnamen haben kein(e) Freizeichen: DispInit(); Wenigstens ein Freizeichen wird nach jedem Komma benötigt um Funktionsargumente zu trennen: DispStr(x, y, s); Wenigstens ein Freizeichen wird nach jedem Strichpunkt benötigt: for (i = 0; i < 10; i++) Die unären Operatoren werden ohne Freizeichen zwischen Operator und Operand geschrieben:!value ~bits ++i j-- (INT32U)x *ptr &x sizeof(x) Die binären (und ternären) Operatoren werden mit mindestens einem Freizeichen zwischen Operator und Operand geschrieben: c1 = c2; x + y i += 2; n > 0? n : -n; a < b c >= 2 Datei:c_coding.doc Seite 10

11 Den Schlüsselwörter if, else, while, for, switch and return folgt ein Freizeichen. if (a > b) while (x > 0) for (i = 0; i < 10; i++) else switch (x) return (y); Das Ist-Gleichzeichen ( '='), und Zahlen sollten untereinander ausgerichtet sein, um ein flüssiges Layout zu erhalten. Achten Sie darauf, dass die LSB s von Integer und Gleitkommazahlen ausgerichtet sind. DispSegTblIx = 0; DispDigMsk = 0x80; DispScale = 1.25; Ausdrücke innerhalb Klammern werden ohne Freizeichen sowohl nach der öffnenden als auch vor der schließenden Klammer geschrieben: x = (a + b) * c; Datei:c_coding.doc Seite 11

12 8.0 Konstrukte Die folgenden Stile für die Konstrukte sollten eingehalten werden: - Einrücken um 4 Freizeichen (space character). - Keine TABs verwenden. - Immer Klammern benutzen, auch für leere Anweisungen. if (x > 0) y = 10; z = 5; if (z < LIM) x = y + z; z = 10; else x = y - z; z = -25; for (i = 0; i < MAX_ITER; i++) *p2++ = *p1++; Array[i] = 0; while (*p1) *p2++ = *p1++; cnt++; do cnt--; *p2++ = *p1++; while (cnt > 0); switch (key) case KEY_BS: if (cnt > 0) p--; cnt--; break; case KEY_CR: *p = NUL; break; case KEY_LINE_FEED: p++; break; 4 Freizeichen einrücken 1 Freizeichen nach for, if, else, while, and switch 1 Freizeichen nach dem ; = untereinander ausrichten 5 Freizeichen bei case einrücken 1 Freizeichen vor und nach Vergleichs- Operatoren Datei:c_coding.doc Seite 12

13 9.0 Funktionen Das Format einer Funktion sollte die folgende Form aufweisen Der Kommentarblock für die Beschreibung der Funktion muss immer dieselbe Form besitzen /* * DESCRIPTION: Function to update all analog inputs. * 1 Space nach dem Funktionsnamen (nur * ARGUMENTS : none in der Deklaration) ermöglicht schnelles * Der Rückgabetyp der Finden der Deklaration anstelle des * RETURNS : none Funktion muss immer Aufrufs und der * angegeben werden. Funktionsimplementierung * NOTES : none */ static void AI_Update (void) INT8U i; AIO *paio; Lokale Funktion besitzt underscore nach dem Modulnamen 2 Space zwischen lokalen Variablen und Code Deklaration und Initialisierung von lokalen Variablen müssen getrennt sein. Also nicht gleichzeitig deklarieren und initialisieren paio = &AITbl[0]; /* Point at first analog input channel */ for (i = 0; i < AIO_MAX_AI; i++) /* Process all analog input channels */ if (paio->aiobypassen == FALSE) /* See if analog input channel is bypassed */ paio->aiopassctr--; /* Decrement pass counter */ if (paio->aiopassctr == 0) ausgerichtet /* When pass counter reaches 0, read and scale AI */ paio->aiopassctr = paio->aiopasscnts; /* Reload pass counter */ paio->aioraw = AIRd(i); /* Read ADC for this channel */ paio->aioscalein = ((FP32)paio->AIORaw + paio->aiooffset) * paio->aiogain; if ((void *)paio->aioscalefnct!= (void *)0) /* See if scaling function defined */ (*paio->aioscalefnct)(paio); /* Yes, execute function */ else paio->aioscaleout = paio->aioscalein; /*No,just cpy data */ paio->aioeu = paio->aioscaleout; /* Out of scal. fnct to E.U. */ paio++; /* Point at next AI channel */ Lange Ausdrücke umbrechen nach 120 Zeichen. Das Multiplikationszeichen ist mit dem = bündig Kommentare sollen nach dem Code beginnen und an Spalte 120 enden Datei:c_coding.doc Seite 13

14 Literatur An Embedded Software Primer David E. Simon Addison Wesley C-Coding Standard Jean J. Labrosse µc/os-ii, The Real-Time Kernel Jean J. Labrosse R&D Technical Books, 1998 ISBN Embedded Systems Building Blocks Jean J. Labrosse R&D Technical Books, 2000 ISBN Datei:c_coding.doc Seite 14