Kommentare, die Sinn machen

[Marnem]

Jeder, der schon mal in einer Softwarefirma gearbeitet kennt das:
Man stößt während des Programmierens auf ein mögliches Problem. Aufgrund des aktuellen Zeitdrucks markiert man sich die Stelle durch einen Kommentar, in dem man auf die Überarbeitungswürdigkeit des Codes hinweist. Natürlich hat man dann nie die Zeit, diese Fehler zu beheben, solange sie nicht zu einem offensichtlichen Bug werden.

Ich möchte hier solche Kommentarzeilen sammeln. Zum einen zur Belustigung, zum anderen als Mahnung. Wenn ihr Code findet und die Lösung schon vor Augen habt, verbessert den Code. Wer weiß was sonst wie Probleme daraus erwachsen...

[Marnem]

// TODO remove the next line
// Block::setDebug(true);

pSP = pStack; // 22.04.2002 is this nescessary ?? TODO TODO

// TODO make sure that consecutive calls to this method work properly

// TODO replace this by memory mapping some day

// TODO this is not really correct

// TODO clear contents of dataprovider here !!

// TODO let this do the compiler instead of saving every field

// TODO wozu ist das hier

// TODO this currently is a workaround; I must change this in the near
// future; that is pData and the recordlist should be unified

// TODO this is also not so nice here

// TODO error

* TODO a magic code for the views combination of fields would be great to
* increase safety for damage by programmers


Dies alles sind Kommentare aus 1 Codedatei mit 4760 Zeilen. Die Datei wurde zuletzt mitte 2003 bearbeitet...

[Ray]

Original geschrieben von Marnem
Jeder, der schon mal in einer Softwarefirma gearbeitet kennt das:
Man stößt während des Programmierens auf ein mögliches Problem. Aufgrund des aktuellen Zeitdrucks markiert man sich die Stelle durch einen Kommentar, in dem man auf die Überarbeitungswürdigkeit des Codes hinweist. Natürlich hat man dann nie die Zeit, diese Fehler zu beheben, solange sie nicht zu einem offensichtlichen Bug werden.

Neben dem "ToDo" Kommentar sollte der Entwickler den möglichen Bug sofort in die Fehlerdatenbank mit dem Querverweis auf die Codestelle einkippen, ihn auf "Nachtesten" setzen und den "ToDo" Kommentar um die Fehlernummer ergänzen. So bleibt die Information nicht beim SW-Entwickler, sondern wird allen Projektbeteiligten (Projektleiter, Tester usw.) zur Verfügung gestellt.
Je nachdem, ob der Bug dann tatsächlich auftritt und je nach Priorität wird er dann gefixt werden müssen, oder zumindest in sowas wie "Nice to have" oder "To Fix in next Release" überstellt werden.
Wichtig ist, daß die Information nicht verloren geht. Vielleicht ist der Bug bzw. das Problem im aktuellen SW-Release nicht relevant, aber der Entwickler ahnt z.B. schon, daß im nächsten Release die ToDo-Stelle zum Problem werden wird. Wo die Manager für das nächste Release nur die Aufwände für neue Features sehen, kann der Entwickler mit entsprechend kommentierten Fehlern in der Datenbank darauf hinweisen, daß noch weitere Aufwände für das Überarbeiten des alten, getesteten Codes anstehen.

[i_hasser]

Gute Idee mit dem Thread ;D.

Mir fallen momentan leider keine Beispiele ein :(. Ha, eins hab ich doch:



// DEPRECATED
// * Does exactly nothing - earlier use was to give benchmarks the ability to show (to the user) that they're not crashed


Das hier hab ich irgendwo mal über eine Funktion geschrieben

// Tree_AddEntry_DataPos... says all

// simple and stupid function to determine next following prime

// Init Prime API - do we need that really?

// this equals to modulo 30
te= prime_mod_tab1[PtrCur&0xFF]+prime_mod_tab2[(PtrCur&0xFF00)>>8]+
prime_mod_tab2[(PtrCur&0xFF0000)>>16]+prime_mod_tab2[PtrCur>>24];



Tja, in der Regel bügele ich sowas schon aus. Hab nix mehr gefunden wie "some shitty code to do..." das ich dann vor sowas setze ;).

[PuckPoltergeist]

/*
* Please skip to the bottom of this file if you ate lunch recently
* -- Alan
*/
-- from Linux kernel pre-2.1.91-1


+#if defined(__alpha__) && defined(CONFIG_PCI)
+ /*
+ * The meaning of life, the universe, and everything. Plus
+ * this makes the year come out right.
+ */
+ year -= 42;
+#endif
-- From the patch for 1.3.2: (kernel/time.c), submitted by Marcus Meissner


/* Fuck me gently with a chainsaw... */
linux-2.0.38/arch/sparc/kernel/ptrace.c


/* Binary compatibility is good American knowhow fuckin' up. */
linux-2.2.16/arch/sparc/kernel/sunos_ioctl.c

[Ray]

Zwei alte hab ich auch noch gefunden:

Bugfixing kurz vor Schluß:

...
if ( ... )
{
// Mister X: Die Abfrage (...) wurde eingefügt wegen des Problems beim
// Initieren des Telefonbuches über die Joker-Taste im Verbundenmenü. Achtung !!!! Vielleicht
// gibt es jetzt unbekannte Nebeneffekte !!!!!

Das Macro chMSG() gibt den Text mit Sourcezeile beim Compilieren aus:

...
case ...:
default:
#pragma chMSG(AT-Keine_Ahnung: Was machen wir nur bei unmöglichem State...)
// Was ist denn jetzt los??? ...
break;

Oder das:

/****************************************************************************
* Additional check for stupid situations:
*/
switch (bAuEvent)
{
case ...:
case ...:
case ...:
if (...)
{
/*
* Bug fix: Avoid further melody playing if ringer was not switched off by
* UI when going to new audio mode!
* NOTE: This does only work with au_func.c since Revision: 1.28!
*/
}
default:
break;
}


Hab bestimmt noch mehr, aber ich möchte nicht, daß irgendwelche Kollegen das wieder erkennen, deshalb auch den eigentlichen Code entfernt ... ;D

[mtb][sledgehammer]

Bei mir gibts eigentlich nur zwei verschiedene Kategorien von Kommantaren, wenn mir mal ein spezieller über den Weg läuft ergänze ich ihn:
1.\ Der echte Kommentar, mit dem ich kommentiere was spezieller Code macht, der nicht sofort nachvollziehbar ist, bzw. bei deklarierten Variablen, wofür sie stehen:
2.\ Platzhalterkommentare nach folgenden Prinzipien
// Hier ist noch Funktion xy hinzuzufügen

// Diese Funktion ist noch allgemeiner zu formulieren

// Ist noch buggy Die entstehen immer dann, wenn ich im Moment nicht den Nerv habe, eine komplexe Fuktion auszuformulieren