Arduino LED Effekt springender Ball

Hallo,

könnte jemand bitte einmal das folgende Programm nachschauen und mir erklären, ob meine Dokumentation soweit dazu richtig wäre?
Falls das nicht der Fall sein sollte könnte dann jemand bitte mir meine Fehler erklären?
Gibt es eigentlich eine deutsche Beschreibung für die ganzen Variablen?

[code]
int LEDPins [] = {6,7,8,9,10}; //Feld mit den Namen LEDPins, welches die Ausgänge 6-10 unter einer Variable zusammenfasst
int ZeitproLED;                //Variable, die festlegt, wie lange die LED an sein soll 
int Richtung = 1;              //Variable, die den Startwert 1 besitzt und die Richtung festlegt
int DerzeitigeLED = 0;         //Variable, die den Startwert 0 besitzt und LED festlegt, die derzeit an ist 
unsigned long Zeitwechsel;     //Variable, die die Zeit für den Wechsel von einer zu anderen LED festlegt


void setup() {                 //Mit dieser Klammer wird die Setupfunktion geöffnet
for (int i=0; i<5; i++)        //For-Schleife mit der Variable i, die von 0 bis 4 hochgezählt wird. i++ zählt die Zählervarriable i um eins hoch
{                              //Mit dieser Klammer wird die For-Schleife geöffnet
  pinMode(LEDPins[i],OUTPUT);  //Festlegen der Pins als Ausgänge, an denen die LEDs angeschlossen sind
}                              //Mit dieser Klammer wird die For-Schleife geschlossen
Zeitwechsel=millis();          //Speichern der millis (Zeit seit dem das Programm gestartet wurde)unter der Variable Zeitwechsel
}                              //Mit dieser Klammer wird die Setupfunktion geschlossen

void loop() {                           //Mit dieser Klammer wird die Loopfunktion geöffnet
ZeitproLED = analogRead(A0);            //Speichern der Werte des analogen Eingangs A0 unter der Variable ZeitproLED
if ((millis()-Zeitwechsel)>ZeitproLED)  //Ist die Different aus den Millis und den Zeitwechsel größer als die ZeitproLED, dann 
{                                       //Mit dieser Klammer wird die IF-Schleife geöffnet
  LEDWechseln();                        //Wird die Unterfunktion LEDWechseln
 Zeitwechsel=millis();                  //Speichern der millis (Zeit seit dem das Programm gestartet wurde)unter der Variable Zeitwechsel         
}                                       //Mit dieser Klammer wird die IF-Schleife geschlossen
}                                       //Mit dieser Klammer wird die Loopfunktion geschlossen 

void LEDWechseln()                                      
{                                       //Mit dieser Klammer wird die Unterfunktion LEDWechseln geöffnet
  for (int i=0; i<5; i++)               //For-Schleife mit der Variable i, die von 0 bis 4 hochgezählt wird
{                                       //Mit dieser Klammer wird die For-Schleife geöffnet
  digitalWrite(LEDPins[i],LOW);         //Die Ausgänge der Variable LEDPins (6-10) werden auf LOW-Pegel festgelegt (alle LED aus)
}                                       //Mit dieser Klammer wird die For-Schleife geschlossen

digitalWrite(LEDPins[DerzeitigeLED],HIGH); //Legt die derzeitige LED als Ausgang fest und auf HIGH-Pegel, die derzeitige LED wird eingeschaltet
DerzeitigeLED += Richtung;                 //Die derzeitige LED wird mit der Richtung addiert 
if (DerzeitigeLED ==4)                     //IF-Schleife, die überprüft, ob die derzeitige LED 4 ist, wenn das der Fall ist, dann wird...
{                                          //Mit dieser Klammer wird die IF-Schleife geöffnet
  Richtung =-1;                            //Die Richtung runtergezählt 
}                                          //Mit dieser Klammer wird die IF-Schleife geschlossen                                  
if (DerzeitigeLED ==0)                     //IF-Schleife, die überprüft, ob die derzeitige LED 0 ist, wenn das der Fall ist, dann wird...
{                                          //Mit dieser Klammer wird die IF-Schleife geöffnet
  Richtung = 1;                            //Mit dieser Klammer wird die IF-Schleife geöffnet
}                                          //Mit dieser Klammer wird die IF-Schleife geschlossen  
}                                          //Mit dieser Klammer wird die Unterfunktion LEDWechseln geschlossen

[/code]

Weniger ist mehr! Die Kommentare sind absolut übertrieben. Was heißt deutsche Beschreibungen der Variablen?

Marvin97:
... könnte jemand bitte einmal ...

Ich finde die Kommentare auch viel zu umfangreich. Überlege Dir, ob Du das zu einem großen Teil in ein „README“ oder sonst eine Doku verschieben kannst. Kommentare sollen IMO lediglich Dir oder einem anderen Programmierer helfen, sich schnell zurecht zu finden. Wenn Du obendrein erklären möchtest, was/warum/wie funktioniert, tu das besser in einer separaten Doku, wenn es um Algorithmen geht, evtl. als Programmablaufplan.

Gruß

Gregor

Wann welche geschweifte Klammer öffnet und schließt ergibt sich aus den entsprechenden Einrückungen. Da solltest du nacharbeiten. Bei der Gelegenheit kannst du auch auf die Formulierung "if-Schleife" verzichten, sowas gibt es schlicht und ergreifend nicht.

sschultewolter:
Weniger ist mehr! Die Kommentare sind absolut übertrieben. Was heißt deutsche Beschreibungen der Variablen?

Mit deutsche Beschreibung war diese Seite (Arduino Reference - Arduino Reference) gemeint, jedoch in deutscher Sprache zur besseren Verständlichkeit.

Könnte mir jemand vielleicht ein Beispielsketch schicken, den er selber programmiert und kommentiert hat, damit ich mir anschauen kann, wie man einen Sketch am besten kommentiert?

Marvin97:
Könnte mir jemand vielleicht ein Beispielsketch schicken, den er selber programmiert und kommentiert hat, damit ich mir anschauen kann, wie man einen Sketch am besten kommentiert?

Die „beste“ Art, einen Sketch zu kommentieren gibt es AFAIK nicht. Dazu gibt es zu viele Rahmenbedingungen, die variieren können. Manchmal hat man mit Vorgaben zu tun, die ein Team oder ein Auftraggeber formuliert. Dann ist es das Beste, genau so zu dokumentieren, wie es vorgegeben ist.

Versuche einfach, so zu dokumentieren, dass es jemand versteht, der sich nur wenig auskennt. Wenn Du in ein paar Monaten immer noch verstehst, was womit gemeint ist, und den Sketch nach Deinen Wünschen erweitern kannst, ist es gut. Wenn Du erst den Code analysieren musst, um die Kommentare zu verstehen, ist es nicht so gut.

Manche Leute kommentieren nur, was eine Funktion bekommt und was sie zurückgibt. Was dazwischen passiert, ist vielleicht gar nicht interessant.

Was „gut dokumentiert“ ist, bekommst Du im Laufe der Zeit heraus und worauf Du beim Dokumentieren achten musst, ebenfalls.

IMO ist es zu sehr eine Stilfrage, um es richtig festklopfen zu können.

Gruß

Gregor

Wenn es dir neu war, was das Gleichheitszeichen in

int Richtung=1;

bedeutet, kannst du das natürlich kommentieren.
Aber, ich verspreche dir, das wirst du nie wieder brauchen.

Aber warum du die Variable definiert hast, warum sie den Wert 1 hat, und was das bedeutet, welche Werte sie sonst noch haben könnte mit deren Bedeutungen, das kann man der Zeile nicht ansehen. Das hast auch du selbst bald wieder vergessen, oder musst dafür den kompletten Sketch durchsuchen.
Das wären Informationen, die an der Stelle wo die Variable definiert wird, gut aufgehoben sind.

Mal ganz abgesehen davon, dassint selten der optimale Datentyp ist.