Programmkommentare Verbesserungsvorschläge

Davide

Mitglied
Was haltet ihr von den Komentaren, sind sie verständlich oder gibt es Komentare im Programm die man gleich weglassen könnte?

Java:
 /**
 * Main.java
 * @author Davide
 * @version 22.12.2010
 *
 * Diese Klasse ist zuständig für die Instanzierung der kontroll Klassen des Packages Start
 * und nach einer erfolgreichen Kontrolle oder Widerherstellung von fehlenden Ordner
 * für die Instanzierung des Hauptprogramms.
 */

package Main;

import Dialogs.RestoreDialog;
import Start.FolderControll;
import Start.RuntimeControll;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.swing.UIManager;
import javax.swing.UnsupportedLookAndFeelException;


public class Main{

    public static void main(String args[]){
        
        try {

            //LookAndFeel des Programms wird auf das des Systems gesetzt.
            UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());
        } catch (ClassNotFoundException ex) {
            Logger.getLogger(Main.class.getName()).log(Level.SEVERE, null, ex);
        } catch (InstantiationException ex) {
            Logger.getLogger(Main.class.getName()).log(Level.SEVERE, null, ex);
        } catch (IllegalAccessException ex) {
            Logger.getLogger(Main.class.getName()).log(Level.SEVERE, null, ex);
        } catch (UnsupportedLookAndFeelException ex) {
            Logger.getLogger(Main.class.getName()).log(Level.SEVERE, null, ex);
        }

        //Gibt Auskunft darüber ob das Programm bereits gestartet wurde.
        boolean isRunning = false;

        //Gibt Auskunft darüber ob alle benötigten Ordner vorhanden sind.
        boolean foldersExist = false;

        //RuntimeControll wird instanziert.
        RuntimeControll runtimeControll = new RuntimeControll();

        //FolderControll wird instanziert.
        FolderControll folderControll = new FolderControll();

        //Prüft ob das Programm bereits gestartet wurde.
        isRunning = runtimeControll.isAnotherInstanceRunning("instance");


        
        if(isRunning == true) {  //Beendet das Programm, falls es bereits gestartet wurde.

            runtimeControll.exitApplication();
        }

        else {

            //Prüft ob alle benötigten Ordner existieren.
            foldersExist = folderControll.existAllFolder();


            if(foldersExist == false) {  //Stellt die bnötigten Ordner wieder her, falls sie nicht existieren.

                //RestoreDialog wird initialisiert
                RestoreDialog restoreDialog = new RestoreDialog(null, true);

                //Die Namen der zu Widerherstellenden Ordner werden übergeben.
                restoreDialog.setRestorableFoldername(folderControll.getRestorableFoldername());

                //RestoreDialog wird auf sichtbar gestellt.
                restoreDialog.setVisible(true);

                
                if(restoreDialog.foldersAreRestored == true) {  //Startet das Programm, wenn alle Ordner wieder vorhanden sind.

                    System.out.println("Programm wird jetzt gestartet.");
                   /**
                    * Programm wird hier gestartet
                    */
                }

                else {  //Beendet das Programm falls nicht alle Ordner wieder vorhanden sind.

                    System.err.println("Ein unbekannter fehler ist aufgetretn, "
                    + "fehlende Ordner konnten nicht vollständig Wiederhergestellt werden.");

                    //Programm wird beendet.
                    System.exit(0);
                }
            }

            else {  //Startet das Programm wenn alle Ordner vorhanden sind.

                 System.out.println("Programm wird jetzt gestartet.");
                 /**
                  * Programm wird hier gestartet.
                  */
            }
        }
    }
}
 

tagedieb

Top Contributor
Kommentare sollten dass Ausdruecken, was du erwartest und nicht nur den Code kommentieren.

Solche Kommentare erachte ich nicht als Hilfreich, da sie nur kommentieren was bereits in deinem Code steht:
Code:
//RuntimeControll wird instanziert.
//FolderControll wird instanziert.
Dass da was instanziert sieht jeder, da braucht es keinen Kommentar, aber kannst (falls noetig) Beschreiben was diese Instanz machen soll

Code:
//RestoreDialog wird auf sichtbar gestellt.
besser: RestoreDialog wird dem Benutzer angezeigt.
Denn sollte aus irgendeinem Grund dein GUI Thread blokiert sein und der Dialog wird nicht angezeigt, scheint in deinem Fall alles richtig zu sein. Der RestoreDialog wurde auf sichtbar gestellt, nur passiert halt nichts.

PS. Control schreibt sich im Englischen mit nur einem 'l'.
 

ARadauer

Top Contributor
Was haltet ihr von den Komentaren, sind sie verständlich oder gibt es Komentare im Programm die man gleich weglassen könnte?
Stimmt ein Kommentar sollte beschreiben, was passiert und nicht wie.

Deinen Kommentar ganz oben versteh ich noch.
Alle anderen Kommentare sind nutzlos und eher hinderlich, schreib mir eine PM mit deiner Mail Adresse. Ich schick dir etwas, was dir hier hilfreich sein könnte...
Generell bevor du die Kommentare wieder raus wirfst, würd ich mit dem Lehrer drüber reden.. Gibt genu von der alten schule, die schon der Meinung ist das man ein kundenDao.delteKunde(kunde); kommentieren muss..
 

Marco13

Top Contributor
Der Klassenkommentar sollte über die Klasse. Ich finde (subjektiv) dass Kommentare auf Englisch sein sollten. Es muss ja kein elaboriert-eloquentes linguistisches Meisterwerk sein, aber lieber "einfaches" Englisch als tolles Deutsch.
Über sowas wie
Code:
//Gibt Auskunft darüber ob alle benötigten Ordner vorhanden sind.
boolean foldersExist = false;
kann man sich streiten. Man könnte so einen Kommentar IMHO weglassen. Den Raum der möglichen Empfehlungen zwischen "so lassen" und "weglassen" kann man ausfüllen mit sowas wie
Code:
// Indicates whether all required [b]foldersExist[/b]
boolean foldersExist = false;
oder
Code:
/* No comment ;-) */
boolean allRequiredFoldersExist = false;
 

Davide

Mitglied
Hab das Gefühl, dass mich das schreiben von guten und sinnvollen Kommentaren mehr Zeit kosten wird, als das Schreiben des Programms. :D
Code:
/* No comment ;-) */
boolean allRequiredFoldersExist = false;
Hat was dieser Kommentar, gefällt mir. :lol:
 
Zuletzt bearbeitet:
J

JohannisderKaeufer

Gast
Was mir merkwürdig vorkommt:

Für die Exceptions die das Setzen des LaF werfen kann wird ein Logger verwendet.
Später wird aber munter mit auf die Console gedruckt?

Dann
if(isRunning == true)
ist das selbe wie
if(isRunning)

Jetzt folgt der Kommentar //Beendet das Programm, falls es bereits gestartet wurde.
Warum logst du hier nicht einfach
logger.log(Level.INFO, "Programm wird beendet, da bereits eine Instanz läuft.");
Hier würde dann aus dem Logeintrag herausgehen was gemacht wird. Und zur Laufzeit sieht man auch ohne Debugger was passiert.

Alles in allem würde ich daraus folgendes machen.
Java:
        if(runtimeControll.isAnotherInstanceRunning("instance"))
        {  
            logger.log(Level.INFO, "Programm wird beendet, da bereits eine Instanz läuft.");
            runtimeControll.exitApplication();
        }

Was isAnotherInstanceRunning("instance") bedeutet würde ich per JavaDoc in runtimeControll kommentieren. Will ich also wissen was da passiert halte ich in Eclipse meine Maus darüber und schau mir den JavaDoc kommentar an. Interessiert es mich momentan nicht, nimmt es mir keinen Platz auf dem Bildschirm weg.

Zeile 80-86 und 98 - 104 sieht ziemlich nach Doppeltem Code aus.

Stellt man das um
Java:
if(!foldersExist){
  if(tryToRestoreFolders()){
    logger.log(Level.INFO, "Unbekannter Fehrler, Ordner...");
    System.exit(0);
  }
}
logger.log(Level.INFO, "Programm wird jetzt gestartet");
...Programm starten

/**
*  Hier dann Javadoc einsetzen
*  @param folderControll ...
*  return true if folders could be restored else false
*/
private static boolean tryToRestoreFolders(Object folderControll){
  RestoreDialog restoreDialog = new RestoreDialog(null, true);
  restoreDialog.setRestorableFoldername(folderControll.getRestorableFoldername());
  restoreDialog.setVisible(true);
  
  return restoreDialog.foldersAreRestored;

}

Kann man den Doppelten Code umgehen. Packt man den Code zum überprüfen der Ordner und deren Wiederherstellung in eine Methode, so kann man den Code strukturieren und per JavaDoc kommentieren.
 

Davide

Mitglied
So ich hab mal meine Main Klasse aufgeräumt, hoffe so ist sie besser.

[Java]
/**
* Main.java
* @author Davide
* @version 22.12.2010
*
*
* Diese Klasse startet die Überprüfung zur Feststellung ob das Programm bereits
* einmal gestartet wurde und ob alle benötigten Ordner vorhanden sind. Waren
* alle Überprüfungen erfolgreich wird das Hauptprogramm gestartet.
*/

package Main;

import Dialogs.RestoreDialog;
import Start.FolderControl;
import Start.RuntimeControl;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.swing.UIManager;
import javax.swing.UnsupportedLookAndFeelException;


public class Main{

public static void main(String[] args) throws Exception{

try {
UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());
} catch (ClassNotFoundException ex) {
Logger.getLogger(Main.class.getName()).log(Level.SEVERE, null, ex);
} catch (InstantiationException ex) {
Logger.getLogger(Main.class.getName()).log(Level.SEVERE, null, ex);
} catch (IllegalAccessException ex) {
Logger.getLogger(Main.class.getName()).log(Level.SEVERE, null, ex);
} catch (UnsupportedLookAndFeelException ex) {
Logger.getLogger(Main.class.getName()).log(Level.SEVERE, null, ex);
}

//Überprüft ob das Programm bereits einmal gestartet wurde
RuntimeControl runtimeControl = new RuntimeControl();

//Überprüft ob alle benötigten Ordner vorhanden sind
FolderControl folderControl = new FolderControl();

if(runtimeControl.isAnotherInstanceRunning()) {
Logger.getLogger(Main.class.getName()).log(Level.INFO, "Programm läuft bereits.");
System.exit(0);
}

else {
if(!folderControl.existAllFolder()){
if(tryToRestoreFolders(folderControl)){
Logger.getLogger(Main.class.getName()).log(Level.INFO, "Unbekannter Fehrler, Ordner"
+ "konnten nicht vollständig widerhergestellt werden.");
System.exit(0);
}
}

Logger.getLogger(Main.class.getName()).log(Level.INFO, "Programm wird jetzt gestartet.");
}
}

/**
* Ruft ein Dialog zum widerherstellen der fehlenden Ordner auf und übergibt
* ihm die Namen der fehlenden Ordner.
* @param folderControl
* @return true wenn alle Ordner wieder vorhanden sind, sonst false.
*/
private static boolean tryToRestoreFolders(FolderControl folderControl) {

//Stellt die fehlenden Ordner wieder her.
RestoreDialog restoreDialog = new RestoreDialog(null, true);
restoreDialog.setRestorableFoldername(folderControl.getRestorableFoldername());
restoreDialog.setVisible(true);

return restoreDialog.foldersAreRestored;
}
}
[/Java]
 
Zuletzt bearbeitet:

tagedieb

Top Contributor
Davide hat gesagt.:
Hab das Gefühl, dass mich das schreiben von guten und sinnvollen Kommentaren mehr Zeit kosten wird, als das Schreiben des Programms.

Gute und sinnvolle Kommentare zu schreiben ist nicht leicht. Auch hier scheiden sich die Geister...

Einige sagen 'Mein Code ist mein Kommentar'. Wenn du sprechende Namen fuer Methoden und Variablen vergibst und die Methoden kurz und uebersichtlich haelst (Stichwort Reflection) kann man auch auf die noetigsten Kommentare beschraenken.

Das andere Extrem schreibt seine Klassen- und Methodenkommentare bevor sie ueberhaupt mit der Implementierung beginnen.


PS. Schade ich habe die System.out s ganz gut gefunden, da sieht man wenigstens was passiert. Diese Meldungen sind eingentlich nur fuer den User interesant. Ins Logfile sollten aber mehr technische Details festgehalten werden (Status, Exceptions), welche dir helfen den Programablauft oder die Fehlerursache nachzuvolziehen.

Im Fehlerfall wuerd ich aber doch dem Benutzer eine Meldung anzeigen (via Console oder GUI), dass das Program abgebrochen wurde. Du kannst auch fuer Details aufs Logfile verweisen. Es gibt nichts nerfenderes als ein Program, welches keinen Feedback liefert. Laeuft das Program noch? ist es abgebrochen? Eingefroren???
 

Davide

Mitglied
PS. Schade ich habe die System.out s ganz gut gefunden, da sieht man wenigstens was passiert. Diese Meldungen sind eingentlich nur fuer den User interesant. Ins Logfile sollten aber mehr technische Details festgehalten werden (Status, Exceptions), welche dir helfen den Programablauft oder die Fehlerursache nachzuvolziehen.

Die System.outs hab ich später wieder rein getan und nur bei den Exceptions (auch in den anderen Klassen) ein Logger hingetan.

Die rote Schrift irritiert bei positiven Meldungen. :lol:
 

DEvent

Bekanntes Mitglied
Keine Kommentare sind die besten Kommentare. Schreibe dein Programm so, als ob du eine Geschichte schreiben würdest. Dein Programm/Klasse/Methode muss von oben nach unten lesbar sein, wobei ganz oben die ganz allgemeinen Methoden stehen (high level) und weiter unten alles feiner (low level) wird. Dabei darf keine Methode mehr als 2 branches im Code haben und darf nicht länger als 4 oder 5 Zeilen Code sein. Wenn du dich daran hältst, dann sieht deine Klasse wie im Beispiel unten aus.

Der Code im Beispiel ist wie eine kleine Geschichte lesbar.
Java:
	public static void main(String args[]) {
		setSystemLookAndFeel();
		startApplication();
	}

Wir setzen ein System Look&Feel und starten die Application. Das versteht jeder, ist auch logisch. Die Geschichte ist schon zu Ende, wer will kann aber weiter lesen.

Java:
	private static void startApplication() {
		if (isAnotherInstanceRunning()) {
			exitApplication();
		} else {
			startApplicationWithCheckFolders();
		}
	}

Wenn eine Instanz der Application bereits läuft, dann beenden wir. Es läuft ja bereits eine Instanz, was sollen wir noch eine starten? Wenn nicht, dann starten wir unsere Application und wir prüfen die Verzeichnisse. Wieder ist diese kleine Geschichte zu Ende, wer will kann weiter lesen.
Java:
	private static void startApplicationWithCheckFolders() {
		if (isRestorationNeededFoldersSucessfull()) {
			startApplicationNormal();
		} else {
			exitApplicationWithError();
		}
	}

Nur wenn die Wiederherstellung der benötigten Verzeichnisse erfolgreich ist werden wir die Application starten. Wenn sie es nicht ist, dann beenden wir mit einer Fehlermeldung.

Java:
	private static boolean isRestorationNeededFoldersSucessfull() {
		if (areNeededFoldersExists()) {
			return true;
		} else {
			return openRestoreDialog();
		}
	}

Wenn die Verzeichnisse bereits da sind, brauchen wir auch nichts wiederherstellen; die Wiederherstellung ist schon erfolgreich abgeschlossen. Wenn sie fehlen, dann öffnen wir einen Wiederherstellungs-Dialog.

Jede Methode ist eine Geschichte, die in sich klar, kurz und eindeutig ist. Die Geschichte ist vollständig und wer Details wissen will, der kann weiter lesen.

Die Namen der Methoden sind so gewählt, dass sie bereits beschreiben was die Methode macht. Ein Kommentar ist nicht mehr nötig und würde nur den Methodennamen wiederholen. Der Code ist sehr kurz und somit leicht verständlich.


Java:
/**
 * Main.java
 * @author Davide
 * @version 22.12.2010
 *
 * Diese Klasse ist zuständig für die Instanzierung der kontroll Klassen des Packages Start
 * und nach einer erfolgreichen Kontrolle oder Widerherstellung von fehlenden Ordner
 * für die Instanzierung des Hauptprogramms.
 */

import java.util.logging.Level;
import java.util.logging.Logger;

import javax.swing.UIManager;
import javax.swing.UnsupportedLookAndFeelException;

public class Main {

	private static RuntimeControll runtimeControll = new RuntimeControll();

	public static void main(String args[]) {
		setSystemLookAndFeel();
		startApplication();
	}

	private static void setSystemLookAndFeel() {
		try {
			UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());
		} catch (ClassNotFoundException ex) {
			Logger.getLogger(Main.class.getName()).log(Level.SEVERE, null, ex);
		} catch (InstantiationException ex) {
			Logger.getLogger(Main.class.getName()).log(Level.SEVERE, null, ex);
		} catch (IllegalAccessException ex) {
			Logger.getLogger(Main.class.getName()).log(Level.SEVERE, null, ex);
		} catch (UnsupportedLookAndFeelException ex) {
			Logger.getLogger(Main.class.getName()).log(Level.SEVERE, null, ex);
		}
	}

	private static void startApplication() {
		if (isAnotherInstanceRunning()) {
			exitApplication();
		} else {
			startApplicationWithCheckFolders();
		}
	}

	private static boolean isAnotherInstanceRunning() {
		return runtimeControll.isAnotherInstanceRunning("instance");
	}

	private static void exitApplication() {
		runtimeControll.exitApplication();
	}

	private static void startApplicationWithCheckFolders() {
		if (isRestorationNeededFoldersSucessfull()) {
			startApplicationNormal();
		} else {
			exitApplicationWithError();
		}
	}

	private static boolean isRestorationNeededFoldersSucessfull() {
		if (areNeededFoldersExists()) {
			return true;
		} else {
			return openRestoreDialog();
		}
	}

	private static boolean areNeededFoldersExists() {
		return folderControll.existAllFolder();
	}

	private static boolean openRestoreDialog() {
		RestoreDialog restoreDialog = new RestoreDialog(null, true);
		restoreDialog.setRestorableFoldername(folderControll
				.getRestorableFoldername());
		restoreDialog.setVisible(true);
		return restoreDialog.foldersAreRestored;
	}

	private static void startApplicationNormal() {
		System.out.println("Programm wird jetzt gestartet.");
		/**
		 * Programm wird hier gestartet
		 */
	}

	private static void exitApplicationWithError() {
		System.err
				.println("Ein unbekannter fehler ist aufgetretn, "
						+ "fehlende Ordner konnten nicht vollständig Wiederhergestellt werden.");

		// Programm wird beendet.
		System.exit(0);
	}
}
 
Ähnliche Java Themen

Ähnliche Java Themen

Neue Themen


Oben