DHBW Stuttgart, Informatik, Advanced SW-Engineering Aug 2016 Programmierung 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 DHBW Stuttgart, Informatik, Advanced SW-Engineering Aug 2016 Programmierung Source Code Dokumentation Kommentare und Header: • • • • • 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 DHBW Stuttgart, Informatik, Advanced SW-Engineering Aug 2016 Programmierung Source Code Dokumentation (mit Javadoc) 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> 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 DHBW Stuttgart, Informatik, Advanced SW-Engineering Aug 2016 Programmierung Hinweise auf guten Programmierstil Seite 4 DHBW Stuttgart, Informatik, Advanced SW-Engineering Aug 2016 Programmierung QS-Kriterium: Verständlichkeit Namenskonventionen • 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 DHBW Stuttgart, Informatik, Advanced SW-Engineering Aug 2016 Programmierung 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 DHBW Stuttgart, Informatik, Advanced SW-Engineering Aug 2016 Programmierung 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