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.
Zeile für Zeile dokumentieren macht ja keinen Sinn. Ich möchte ja, dass der Leser versteht was in der Initialisierungsroutine passiert.
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?
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.
Was Karl Heinz meinte, könnte etwa so aussehen. ein Auszug aus meinem CAN:
1 | // Assignment of CAN-Message Objects to Functions:
|
2 | // Objects 0 .. 7: Receive Buffer for IO-Change of State Messages
|
3 | #define OBJ_XMIT_IO 8 // Transmit IO-Change of State Messages
|
4 | #define OBJ_REC_DUPM 9 // Receive Duplicate MacId
|
5 | #define OBJ_XMIT_DUPM 10 // Transmit Duplicate MacId
|
6 | #define OBJ_REC_ERM 11 // Receive Explicit Request
|
7 | //#define OBJ_XMIT_ERM 12 // Transmit Explicit Request
|
8 | #define OBJ_REC_UERM 13 // Receive Unconnected Explicit Request
|
9 | #define OBJ_XMIT_UERM 14 // Transmit Unconnected Explicit Request
|
10 | |
11 | |
12 | #define SET_CAN_OBJECT(obj,idh,idl,rxtx,txok) \
|
13 | CANPAGE = (obj) << 4; \
|
14 | CANIDT1 = idh; \
|
15 | CANIDT2 = idl; \
|
16 | if( rxtx ) \
|
17 | CANCONCH = rxtx; \
|
18 | if( txok ) \
|
19 | CANSTCH = txok;
|
20 | |
21 | // ...
|
22 | |
23 | uchar can_init( void ) // Initialize Can-Subsystem |
24 | {
|
25 | |
26 | //...
|
27 | |
28 | SET_CAN_OBJECT( OBJ_XMIT_IO, |
29 | (MacId >> 3) | 0x68, MacId << 5, 0, 0 ) |
30 | |
31 | SET_CAN_OBJECT( OBJ_REC_DUPM, |
32 | MacId | 0x80, 0xE0, CANCONCH_RECEIVER_, 0 ) |
33 | |
34 | SET_CAN_OBJECT( OBJ_XMIT_DUPM, |
35 | MacId | 0x80, 0xE0, 0, CANSTCH_TXOK_ ) |
36 | |
37 | SET_CAN_OBJECT( OBJ_REC_ERM, |
38 | MacId | 0x80, 0x80, CANCONCH_RECEIVER_, 0 ) |
39 | |
40 | SET_CAN_OBJECT( OBJ_REC_UERM, |
41 | MacId | 0x80, 0xC0, CANCONCH_RECEIVER_, 0 ) |
42 | |
43 | SET_CAN_OBJECT( OBJ_XMIT_UERM, |
44 | MacId | 0x80, 0x60, 0, CANSTCH_TXOK_ ) |
Peter
Bitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail? Keine Anmeldung erforderlich!
Mit Google-Account einloggen
Mit Google-Account einloggen
Noch kein Account? Hier anmelden.