CAN_vInit() Funktion

[Patrick (Gast)]

Ich habe da Probleme mit der Dokumentation der Can 
Initialiserungsroutine.
Wie könnte man solch eine etwas umfangreichere Funktion richtig 
dokumentieren?
Für jeden Tipp bin ich sehr dankbar.

[Patrick (Gast)]

Ist da ein Flussdiagramm sinnvoll?

[Patrick (Gast)]

Zeile für Zeile dokumentieren macht ja keinen Sinn. Ich möchte ja, dass 
der Leser versteht was in der Initialisierungsroutine passiert.

[Patrick (Gast)]

Wie würdet ihr da genau vorgehen?

[Karl H. (kbuchegg)]

Kommt drauf an, wer das ganze lesen muss.
Für einen Neuling in Sachen CAN Bus musst du da
wesentlich weiter ausholen als für einen alten Hasen.

Beschreib einfach, welche Aktionen in welcher Reihenfolge
sich am Bus abspielen muessen. Wenn nicht klar ist, warum
eine bestimmte Reihenfolge eingehalten werden muss, dann
sollte man auch das dokumentieren. Wenn da magische Zahlen-
werte auftauchen: Was bedeuten sie? Wie bist du auf sie gekommen?

Ein Leser muss das, was du in den letzten Tagen rausgefunden
hast, nachvollziehen können. Es gibt da kein richtig oder
falsch. Stell dir einfach vor, du musst in einem Jahr das
ganze nochmal machen. Welche Informationen würdest du dazu
benötigen? Und die dokumentierst du.

Was absolut sinnlos ist: Dinge dokumentieren, die sowieso
im Source Code stehen. Ein
    i++;
muss man nicht mit einem Kommentar 'i um 1 erhöhen' versehen.
Dass i erhöht wird sieht ein Blinder mit Krückstock. Viel
wichtiger ist: Warum wird i erhöht?

[Karl H. (kbuchegg)]

Was ich auch noch machen würde:
Brich diese lange Funktion in mehrere Unterfunktionen
auf. Beim drüberscrollen sind mir da einige Funktions-
blöcke ins Auge gesprungen, die man sehr gut in eigene
Funktionen auslagern kann.

Zb. würde dem Code eine Funktion, die 1 Message Objekt
konfiguriert gut zu Gesicht stehen. Der Funktion übergibst
du die relevanten Daten und die Funktion konfiguriert diese
1 Message. In der Init Funktion stehen dann nur noch die
Aufrufe für die x zu konfigurierenden Message Objekte.
Dadurch würde sich dein Code schon mal enorm verkleinern.
Kleinerer Code -> weniger zu dokumentieren.

[Peter D. (peda)]

Was Karl Heinz meinte, könnte etwa so aussehen.
ein Auszug aus meinem CAN:

// Assignment of CAN-Message Objects to Functions:
// Objects 0 .. 7:      Receive Buffer for IO-Change of State Messages
#define OBJ_XMIT_IO      8      // Transmit IO-Change of State Messages
#define OBJ_REC_DUPM     9      // Receive Duplicate MacId
#define OBJ_XMIT_DUPM   10      // Transmit Duplicate MacId
#define OBJ_REC_ERM     11      // Receive Explicit Request
//#define OBJ_XMIT_ERM  12      // Transmit Explicit Request
#define OBJ_REC_UERM    13      // Receive Unconnected Explicit Request
#define OBJ_XMIT_UERM   14      // Transmit Unconnected Explicit Request


#define SET_CAN_OBJECT(obj,idh,idl,rxtx,txok)   \
    CANPAGE = (obj) << 4;                       \
    CANIDT1 = idh;                              \
    CANIDT2 = idl;                              \
    if( rxtx )                                  \
      CANCONCH = rxtx;                          \
    if( txok )                                  \
      CANSTCH = txok;

// ...

uchar can_init( void )                  // Initialize Can-Subsystem
{

//...

  SET_CAN_OBJECT( OBJ_XMIT_IO,
    (MacId >> 3) | 0x68, MacId << 5, 0, 0 )

  SET_CAN_OBJECT( OBJ_REC_DUPM,
    MacId | 0x80, 0xE0, CANCONCH_RECEIVER_, 0 )

  SET_CAN_OBJECT( OBJ_XMIT_DUPM,
    MacId | 0x80, 0xE0, 0, CANSTCH_TXOK_ )

  SET_CAN_OBJECT( OBJ_REC_ERM,
    MacId | 0x80, 0x80, CANCONCH_RECEIVER_, 0 )

  SET_CAN_OBJECT( OBJ_REC_UERM,
    MacId | 0x80, 0xC0, CANCONCH_RECEIVER_, 0 )

  SET_CAN_OBJECT( OBJ_XMIT_UERM,
    MacId | 0x80, 0x60, 0, CANSTCH_TXOK_ )

Peter