Inhalt Aufbau des Source Codes Dokumentation des Source Codes (Layout) Qualitätskriterien berücksichtigen: Verständlichkeit Namenskonventionen Wartbarkeit: Programmierrichtlinien für erlaubte Konstrukte, Schachtelungstiefe, Erwartungskonformität bei der Benutzerschnittstelle Seite 1
Kommentare und Header: Source Code Dokumentation comments shall not contain pseudocode or algorithm description, the code itself explains this! Standard header comment section (first item in the declarations section) for modules and classes (and forms): file name, copyright notice, creation date, original developer, brief description record of changes in the maintenance phase: name of the person making the change, date of the change, brief description of the change Standard header comment section (first item in the declarations section) for procedures, methods, interfaces and templates: brief description of the procedure, description of each parameter & any return value record of changes in the maintenance phase (see above) Variable should have a comment on the same line as the variable declaration (all line up in the same column). If the comment is long, it should be placed on the preceding line Inline comments appear above the code of the program block that they describe proceeded by one blank line Seite 2
Javadoc makes use of flags to generate specific links and markup. These flags include: @author, @version, @param, @see and @return. Javadoc block comments begin with /** on a single line, followed by the comment content, and end with */ on a single line. Beispiel: javadoc Eingabe.java -author version generiert: /*********************************************** <p><b>kurzbeschreibung:</b> Source Code Dokumentation (mit Javadoc) Die Datei enthält die Klasse Eingabe. Sie dient zum Testen einer streambasierten Eingabe mit Konvertierung durch die Klasse InputStreamReader <p> <b>builded:</b> javac Eingabe.java mit Java WorkShop 2.0 @author Christoph Riewerts, Daimler AG, M413 @version V1.000 vom 12/09/15 ************************************************/ public class Eingabe { } // Hier steht die Klassendefinition java.lang.object +----Eingabe public class Eingabe extends Object Kurzbeschreibung: Die Datei enthält die Klasse Eingabe. Sie dient zum Testen einer streambasierten Eingabe mit Konvertierung durch die Klasse InputStreamReader Builded: javac Eingabe.java mit Java WorkShop 2.0 Version: V1.000 vom 12/09/15 Author: Christoph Riewerts, Daimler AG, M415 Seite 3
Hinweise auf guten Programmierstil Seite 4
Namenskonventionen QS-Kriterium: Verständlichkeit In general: the name shall be descriptive and unambiguous, avoid using abbreviation, acronyms and computer jargon unless it is extremely awkward not to do so! Using unique method: Writing notation: newaddress Underscore notation: new_address Consonant notation: nwddrss Hungarian notation with tag and optional qualifier (i.e. fst for first): padr (tag p means pointer), scadr (tag sc means string with a fixed length) Name lengths in the range of 9 to 15 characters are considered optimal In the case of Boolean objects, the name should reflect the object s TRUE condition Path names will not be hard coded into any application Application specific constants will be named as appropriate using all uppercase letters, numbers and underscore (_) characters (with a single lowercase letter prefix for data type, for example tapp_name for a String constant) User defined types will be declared with the data type in capital letters and the components following normal variable conventions Seite 5
QS-Kriterium: Wartbarkeit Vorschlag für Richtlinien für Java-Code (Qualitätsmaß): (Max 10% aller) Methoden dürfen nicht mehr als 20 Statements haben (oder keine Methode darf mehr als 40 Statements aufweisen) Methoden dürfen nicht mehr als vier Parameter haben (Maß: max. 10% aller Methoden haben zw. 5 und 15 Parameter) Methoden haben eine max. McCabe-Komplexität (Schachtelung & Pfade) von 5 (Max. 10% aller) Klassen dürfen nicht mehr als 10 Instanzvariable haben Übergabeparameter dürfen innerhalb einer Methode nicht überschrieben werden Übergabeparameter dürfen nicht denselben Namen haben wie interne Variable In booleschen Ausdrücken sind Konstante statt Werte zu verwenden Alle Variable müssen mit modifiern belegt werden Die Form.* für Import-Anweisung muss vermieden werden Jede return-anweisung ist mit JavaDoc zu kommentieren Seite 6
QS-Kriterium: Ergonomie der Benutzerschnittstelle z.b. Erwartungskonformität (Dialoggestaltung): Information, was das Programm leistet GUI: Im Menüpunkt info oder Zeilenorientiert (zo): direkter Hinweis bei der Programmausgabe Hinweise, wie man das Programm bedient GUI: Online-Hilfe oder Zo: Aufruf mit der Option help oder Zo: direkter Hinweis bei der Programmausgabe Informationen über den Hersteller Name, Version, Copyright, Support-Adresse Eindeutige Fehlerbehandlung Was hat der Benutzer im Fehlerfall verkehrt gemacht? Wie kann er in Zukunft den Fehler vermeiden? Seite 7