Radar Scanner 1.0.0
Loading...
Searching...
No Matches
Styleguide
Author
Sven Steddin
Version
0.2
Date
2019-06-03

Vorwort

Der hier vorliegende Styleguide ist noch im Entwurfsstudium!

Die in diesem Styleguide enthaltenen Vorgaben sind kein allgemeingültiger Standard sondern eine für einen bestimmten Geschäftsbereich definierte Vorschrift zur Formatierung von Source Code Dateien. Diese Vorschriften können von jeder Organisation eigenständig festgelegt werden und individuelle Unterschiede aufweisen. Der hier vorliegende Styleguide soll dieses Konzept beispielhaft verdeutlichen.

Unabhängig von den hier gezeigten Vorgaben gelten natürlich die als good style akzeptierten Vorgaben, wie sie z.B. von xxx beschrieben wurden.

Deklaration von Variablen

Zur Beschreibung der Basistypen von Variablen werden die in <inttypes.h> vorgegebenen Definitionen verwendet. Es ergeben sich folgende Vorteile:

  • kürzere Typbezeichner --> weniger Schreibarbeit
  • maschinenunabhängige Datentypen

Die Definition von Variablennamen erfolgt vorzugsweise in der Kamelhöckerschreibweise.

Variablennamen beginnen mit einem kleinen Buchstaben.

Präfixe für Variablennamen

Es sollen die nachfolgend gelisteten Präfixe bei der Definition von Variablennamen verwendet werden. Es ergeben sich folgende Vorteile:

  • es kann direkt im Sourcecode erkannt werden, ...
    • welchen Datentyp eine Variable besitzt
    • welchen Sichtbarkeit eine Variable besitzt
    • wie der Zugriff auf die Variable zu erfolgen hat
Präfix Bedeutung Beispiel
p_ Variable ist ein Zeiger p_uiEvent
gp_ Variable ist ein global verfügbarer Pointer für Schreib- und Lesezugriffe gp_uiStatus
gcp_ Variable ist ein global verfügbarer Konstantenpointer für Lesezugriffe. Der Inhalt der Variable, auf die der Pointer zeigt, kann über den Pointer nicht verändert werden. gcp_uiTime_ms
m_ Variable ist modulglobal, d.h. nur innerhalb des Moduls sichtbar, in dem sie als static deklariert wird. m_uiWinkelgrad_deg
kein x_ - Präfix Varaible ist nur lokal innerhalb des aktuellen Blocks verfügbar uiZaehler

Abkürzungen für bestimmte Datentypen:
(diese sind maschinenabhängig und beziehen sich hier auf den MSP430)
Die Typabkürzungen werden ohne Trennzeichen direkt dem Variablennamen vorangestellt. Der Variablennamen beginnt dann mit einem Großbuchstaben.

Präfix Bedeutung Beispiel
uc uint8_t ucData
c int8_t cDifference
ui uint16_t uiFrequenz
i int16_t iDistance
ul uint32_t ulCount
l int32_t lValue
f float fGewicht
d double dToleranz



Zugriff auf externe Sensoren / Aktoren

Der Zugriff auf Aktoren oder Sensoren erfolgt über einen standardisierten Satz von Funktionen (API):

XY-Init()

  • Anlegen der für den Datenaustausch erforderlichen Datenstrukturen
  • Konfiguration der MC-Register der für den Zugriff auf die Hardware erforderlichen Peripherals des MC
  • Definition der Registerinhalte der externen Hardware, die ggf. zu Beginn auf die Hardeware übertragen werden müssen
  • Aktivieren der für den Datenaustausch mit der externen Hardware benötigten Peripherals des MC
  • Reset der Hardware

XY-Start()

  • Übertragen der Konfigurationsregister auf die Hardware
  • Start der Funktion der externen Hardware

XY-Write()

  • Schreiben von Daten oder Kommandos auf die Hardware

XY-Read()

  • Lesen von Daten von der Hardware

XY-Stop()

  • Einfrieren des Zustandes der Hardware

    Es gelten folgende Anforderungen an das API:

Sofern bestimmte Funktionen für den Betrieb der Hardware nicht erforderlich sind, können diese weggelassen werden

  • Die Funktionen dürfen das Programm nicht blockieren bzw. müssen abbrechbar sein
  • Die I/O-Funktionen sollen dazu geeignet sein, in Interrupt-Serviceroutinen aufgerufen zu werden
  • Die Funktionen liefern einen Rückgabewert, der den Erfolgsstatus des Funktionsaufrufs kennzeichnet
  • Die Werteübergabe erfolgt über Zeiger auf Datenstrukturen, die für die Nutzung der Funktionen definiert werden müssen

Erstellung von doxygen Kommentaren

Erstellen von File Headers

Zu Beginn jeder Sourcedatei soll ein Header über die Bedeutung der Sourcedatei informieren. Der hier enthaltene Text soll als Vorlage verwendet werden. Die enthaltenen Beispieltexte müssen ersetzt werden. Die Bedeutung der doxygen tags ist der doxygen Dokumentation zu entnehmen:
[doxygen Handbuch] (http://www.stack.nl/~dimitri/doxygen/manual/markdown.html)

Erstellen von Function Headers

Zu Beginn jeder Funktion soll ein Header über die Bedeutung der Funktion informieren. Der hier enthaltene Text soll als Vorlage verwendet werden. Die enthaltenen Beispieltexte müssen ersetzt werden. Die Bedeutung der doxygen tags ist der doxygen Dokumentation zu entnehmen:
[doxygen Handbuch] (http://www.stack.nl/~dimitri/doxygen/manual/markdown.html)

Wichtig:
Nicht verwendete tags sollen entfernt werden, damit die erzeugte Dokumentation möglichst kurz und übersichtlich bleibt. Die tags sind dann bei Bedarf in der vorgesehenen Reihenfolge wieder einzufügen.

//********************************************************************************************************/

Das tag riskman gehören nicht zu den doxygen Standardtags sondern ist eine benutzerabhängige Erweiterungen, die im doxygen Konfigurationsfile unter ALIASES definiert werden muss.

Einsatz von graphviz.dot

Doxygen kann Grafiken zu den Abhängigkeiten der Source-Dateien erstellen, wenn das Tool graphviz-dot auf dem Rechner installiert ist. Der bin-Pfad der Installation muss im doxygen-File hinterlegt sein.

Verwendung von Templates zur Neuanlage von Dateien

Die CCS-IDE ist von Eclipse abgeleitet. Es gibt daher die in Eclipse definierte Vorgehensweise, bei der Neuanlage von Dateien vorkonfigurierte Templates zu erstellen. Die Einstellung der Template erfolgt unter dem Menüpunkt /Window/Preferences/Code Style/Code Templates/Files