Ich will aber...ordentlich Programmieren: Konventionen

[_ebm_]

Trägst Du etwa kein buntes Bändchen?

Im Geiste ja, ich schmücke mich nicht gern, trage eher schwarz...

 

[scope]

Anständig dokumentieren (theoretisch eine Zeile Doku für jede Zeile Code).

Bitte nicht. Das ist kontraproduktiv und, wenn man sauber programmiert und strukturiert gar nicht nötig. Wenn jede Funktion kurz und knackig gehalten wird, eine Aufgabe erfüllt und alles intuitiv benannt ist (Siehe z.B. Apple Code Naming Guidelines) kommt man mit sehr wenig Kommentaren aus und es ist trotzdem auf Anhieb ersichtlich, was passiert.

Viel wichtiger ist, nicht zu kommentieren was da passiert, sonder warum es passiert. Was ist der Grund, das etwas so und nicht anders implementiert wurde. Das ist gerade am Anfang schwer durchzuhalten, weil man sich immer wieder dabei ertappt, doch einfach nur zu beschreiben, was de Code macht.

// Addiert die zwei Zahlen, die als Parameter übergeben werden.
public function add(int a, int b){
    return a+b;
}

Na super…

 

[frauenPower]

Viel wichtiger ist, nicht zu kommentieren was da passiert, sonder warum es passiert. Was ist der Grund, das etwas so und nicht anders implementiert wurde. Das ist gerade am Anfang schwer durchzuhalten, weil man sich immer wieder dabei ertappt, doch einfach nur zu beschreiben, was de Code macht.

Wow, toll formuliert. Wird heute noch oben mit eingebaut.

Danke Dir
Karin

 

[Hausbesetzer]

damit mich auch andere Programmierer verstehen, versuche ich mich an die allgemeinen Konventionen zu halten.

Brauchst Du nicht, wenn Du Dich an Regel 1 hälst: Inlineduku, InlineDoku, InlineDoku

 

[_ebm_]

InlineDoku

Damit zwingst du aber den geneigten Leser des Codes, zwei Sachen parallel zu lesen und zu verstehen - den Code und die Doku! Lieber sauber programmieren und nur wenn nötig, dokumentieren!

 

[iCode]

Brauchst Du nicht, wenn Du Dich an Regel 1 hälst: Inlineduku, InlineDoku, InlineDoku

-1

 

[Hausbesetzer]

Damit zwingst du aber den geneigten Leser des Codes, zwei Sachen parallel zu lesen und zu verstehen - den Code und die Doku!

Gerade ja nicht - nur die Doku.
Aber klar, wenn die Doku Mist ist (und das ist sie in 99% der Fälle) dann muss man den Code danach nochmal lesen um zu verstehen, was gerade überhaupt los ist.

 

[_ebm_]

Ich lese für gewöhnlich den Code, denn der tut die Arbeit, nicht die Doku...

 

[_ebm_]

Mir fällt noch eine wichtige Konvention ein, die unabhängig von der Sprache ist. "Lieber explizit als implizit!"

Beispiel: Mache keine Annahmen über Zustände an anderen Stellen im Code (in einem anderen Thread). Wenn du nur vermutest, weißt du es nicht. Wenn woanders etwas berechnet wird, warte nicht 1000ms und probiere es dann, lasse dich benachrichtigen, wenn es fertig ist (-> delegator/callback)

 

[felix88]

Damit zwingst du aber den geneigten Leser des Codes, zwei Sachen parallel zu lesen und zu verstehen - den Code und die Doku! Lieber sauber programmieren und nur wenn nötig, dokumentieren!

So was ist Dockumentation einer Software eigentlich alles scheint hier ja nicht ganz klar zu sein:
Analyse
Spezifikation
Entwurf
Systemtestplan
sind die wichtigsten Dockumente.

In großen Projekten ist die Aufwandsverteiliung ,innerhalb der Entwicklung, nach der man streben sollte ca 60/15/25 (vor, für und nach der Codierung)

Man sieht Codierung ist ein sehr kleiner Teil des Aufwandes für eine Entwicklung. In diesen 15% Codierungsaufwand ist die Code-Dockumentation mit einberechnet. Das hört sich sehr extrem an, ist aber notwendig wenn man bedenkt das mehr wie 90% der Kosten wärend der Wartung entstehen.

Man muss nicht dockumentieren es ist aber sinvoll. Es gibt genug abschrekende Beispiele für große Projekte die nicht dockumentiert wurden. Es ist nahezu unmöglich diese Systeme zu warten man macht es trotzdem. Macht euch klar was es heisst einen Bug zu finden in 50k+ module die nur incode schlecht oder gar nicht Dockumentiert sind.

Mit Software Entwicklungs Prozessen und Werkzeugen werden Millarden umgesetzt. Der jeweils eingesetzte Entwicklungs Prozess ist oft ein Betriebsgeheimnis.

Wenn man nur für sich etwas aus Spass entwickelt kann natürlich auf eine Ausführliche Dockumentation verzichten. Aber ab dem Moment wo es um große Projekte geht, die über Jahre laufen, ist es ein muss. Ein Projekt ist schnell gegen die Wand gefahren, viele Firmen gehen zu Grunde weil sie ihre Projekte nicht richtig im Griff haben.

Immer auf die Dockumentation achten wenn ihr länger an etwas arbeitet werdet ihr sie irgendwann schätzen. Sei es auch nur dass ihr nach einem halben Jahr einen Bug fixen müsst, ihr werdet ihn schneller finden.

 

[cropfaktor]

Ware Worte.
In der DB-Entwicklung gehen schonmal 60% der Zeit für die Normalisierung drauf und Gnade Dir Gott, wenn Du da nicht ordentlich bist...
Dokumentieren ist das A und O und wer beschreiben kann, um was es aktuell geht, der weiss auch worum es geht.
Ich kenne einige begnadete VBA-Menschen, die Null umgesetzt haben, weil sie sich endlos in der Schönheit der Lösung eines Teilaspektes verzettelt haben. An der fehlenden Doku oder auch nur am fehlenden Tagesbericht sieht man dann, dass man einschreiten muss.

 

[_ebm_]

Hm ich wurde falsch verstanden. Ich meinte die In-Code-Dokumentation! Schreibst Du sauberen Code, musst Du ihn kaum dokumentieren. Anders sieht es mit APIs, Datenmodellen, mathematischen Modellen, dem System und anderen "Nebensächlichkeiten" (meine Hauptaugenmerk!) aus. Das ist zu dokumentieren, und zwar so ausführlich wie möglich. Wie hängt was zusammen? wie sieht das Domänenmodell der Anwendung aus? Welche Funktionalität steckt eine API ab. Wie sah die Entscheidungsfindung für Bibliotheken, Tools, Sprache und so weiter aus? Welche Absprachen bestehen zwischen Auftraggeber und Entwickler? Da gibt es so vieles, das man festhalten muss und nimmt in der Tat sehr viel Zeit in Anspruch. Das ist wohl auch die Hauptarbeit eines Entwicklers. Ich schrieb ja auch vor kurzem in einem der gerade akuten Threats, Programmieren ist Handwerk. Die Arbeit besteht hauptsächlich aus dem, was im Kopf (und auf dem Papier) passiert. Das Runterschreiben des Codes ist pure Fleißarbeit, nicht das Dokumentieren!

 

[Hausbesetzer]

Schreibst Du sauberen Code, musst Du ihn kaum dokumentieren.

Doku Doku Doku.

 

[_ebm_]

Mein guter Hausbesetzer, wenn Du im Code stellen begleitend dokumentieren musst, ist der Code an der Stelle zu komplex und du solltest ihn herunterbrechen, verwende dabei sprechende Namen. Achte darauf, dass ein Statement nur eine Funktion hat. Achte darauf, dass eine Methode nicht mehr als 100 Zeilen hat. Dann musst du nicht begleitend schreiben, was du da tust. Sonst stört die Doku Deinen Lesefluss und im Falle einer Änderung musst Du zwei Texte pflegen.

Verwende potentiell schwer verständliche Dinge wie RegEx, Lambda-Expressions, Pointer Arithmetik und ähnliches nur, wenn Du Dir Lesbarkeitsvorteile oder deutliche Geschwindigkeitsvorteile erhoffst.

 

[_ebm_]

Da fällt mir noch ein Zen ein: Premature optimization is the root of all evil in programming! Schreibe Code erst gut verständlich auf, Optimiere erst, wenn Du merkst, dass der Code zu langsam läuft!

 

[Naphaneal]

Doku Doku Doku.

code sollte so geschrieben sein, daß er ohne doku zu verstehen ist...zumindest im großen ganzen...

ansonsten, ja.

achja...je mehr du über code nachdenkst, desto weniger musst du debuggen...

 

[scope]

In den meisten Fällen ist Dokumentation auf höheren Ebenen viel wichtiger und auch hilfreicher als die Dokumentation einzelner Funktionen.

Die Funktionen sind, wie ja schon gesagt wurde, im Idealfall sowieso kurz und prägnant, so dass man am Namen schon ablesen kann, was passiert. Dazu noch Ein- und Ausgabeparameter beschreiben (In welcher Form müssen Daten rein, wie kommen sie raus, welche Fälle gibt es) und das war's. Je nach Programmiersprache geht das sehr kurz und gleichzeitig eindeutig.

Viel wichtiger ist gerade bei komplexen Systemen, die gewartet werden müssen, meist außerhalb des Codes in einer externen Dokumentation, zu beschreiben, wofür die einzelnen Teilmodule gedacht sind, wie sie miteinander kommunizieren und wie grundsätzlich das System aufgesetzt ist (MVC, etc.). Es ist viel häufiger das Problem, dass grundsätzlich das Verständnis fehlt, wie Abläufe innerhalb des System erfolgen. Wenn man erstmal soweit ist, sich bei einem vormals fremden System mit einzelnen Funktionen im Detail auseinandersetzen muss, sollte eigentlich das Grundverständnis schon lange vorhanden sein.

Man sollte bei dem ganzen Gerede über optimalen, prägnanten, gut dokumentierten Code aber auch nicht vergessen, dass das Refactoring ein entscheidender Teil von Software-Entwicklung ist. Man schafft es quasi nie, vorweg alles so zu planen und vorherzusehen, dass das reine Programmieren nur noch ein Runterschreiben ist. Das habe ich noch bei keinem Projekt erlebt. Viel wichtiger ist es, regelmäßig existierenden Code anzugehen und ihn dahingehend zu überprüfen, ob er den Anforderungen noch gewachsen ist, ob er sich noch sauber in die Strukturen einfügt, usw. Wenn man an dieser Stelle nicht ansetzt und den Code "wartet" hat man nachher trotz ausreichender Dokumentation ein Riesengewächs, dass dreimal so komplex ist, wie es sein müsste und ungenutzten Code an jeder Ecke der unnötig Wartungsarbeit, etc. erfordert.

 

[buk]

Ihr solltet Euch mehr auf das wesentliche[1] konzentrieren

[1] http://programming-motherfucker.com/