User Interface Programming OOP/Java Primer Step 3 - documentation Department of Information Technology Uppsala University
What is the documentation? Documentation about program in the program Clearly written code (!) Good naming Conventions Expressive names Anything else that makes the program easy to read and understand!
Good programming style Good structure Modularity Programming concepts Clarity Naming conventions Clear coding Documentation Public documentation Javadoc Internal documentation commented code
Good Programming Style implies Good Documentation
Quick guidelines Make the code clear and easy to read. Make the code consistent. Use obvious identifier names. Logically organize your files and classes. Have only one class per file (not including inner classes). Use a maximum line width of 80-90 characters. Use whitespace and/or other separators judiciously. Use spaces instead of tabs for indentation.
Good structure The structure of a program should mirror the purpose of the program Package structure File structure Class structure Indentation! Avoid having more than 2000 lines in one file Including documentation
Well-considered: Purpose? Purpose of program Purpose of package Purpose of class Purpose of method
Modularity Files in the same package should have a common higher theme Use subpackages to structure large packages Cf. The API structure! Name every package! Don t put files in the default package
Programming Concepts Make sure you display the intention of the code through the programming concepts Loops what is the loop doing? Is it a loop or a pass through a collection? Data structure what are they storing?
Example for (int i = 0;i<100; i++) { check(x[i]); } or Iterator iterator = x.iterator(); while(iterator.hasnext()) { check(iterator.next()); }
Programming Concepts Programming concepts have a meaning Clear use of concepts makes the code more transparent Even if the code works it might still be contradictory
Clarity The code should be clear and readable Indentation shows scope! Variable scope can be difficult to judge Variable names should display the content Method names should display what they do
Conventions Loop variables: i,j,k,m,n, commonly used in non-semantic loops loop through arrays, pixelmaps etc the indexes have no meaning in themselves Coordinate variables: x,y,z,... a commonly used for working with GUI positions pixelmaps where we are interested in the pixel value (a = normally alpha value) Following conventions increases readability
Temporary variables The name temp can be used, but should be complemented by the content type: tempfile, tempcounter, tempname Temporary variables are not just temporary holders of information, they are TYPED! Be careful with scope Don t reuse a temporary variable in other places!
Variables Be generous with letters Use long names! Use describing names Make the names unique (not sum1, sum2, etc.) Use of the wrong variable is easier to detect, if you have longer, meaningful names, cf. s = h/k
Variables Be generous with letters Use long names! Use describing names Make the names unique (not sum1, sum2, etc.) Use of the wrong variable is easier to detect, if you have longer, meaningful names, cf. s = h/k speed = hours/kilometers
Methods The name of a method should tell the story Use long names if needed The compiler will detect errors for you if you spell them wrong NetBeans will suggest the method for you Long, meaningful names will enhance the readability of the code
Long, meaningful names One important drawback! Make sure to also change the name, if you change the functionality!!! If you correct a conceptual bug, the name might have to change: addinterest(int sum) needs to change name if we change the functionality so that it subtracts the interest
Clear Coding Avoid smart solutions It is better to have a few more steps in the code The Compiler will most of the time be able to optimize it. A temporary variable is cheap Try to make clear steps in the code Make sure the code is logical Finish one thing in the code before starting a new Don t mix several tasks in the code unless necessary
Complex code If you need to write complex code in a method you should provide one of: pseudo code in the comments an English description of what you are doing Not the procedure, but the effect! Complex code could sometimes be rewritten Can you extract part of it as a separate method? Can you indent or restructure the code for better readability?
Complex code Some ways to approach complex code: Try to explain it to a fellow programmer Try to explain it to a non-programmer
Documentation Public documentation: Javadoc Documentation follows specific rules Special sections and keywords Compiles to an API description Local documentation Documents the thoughts in the code Supports understanding, reading and debugging Just as important as the public Documentation
Javadoc A documentation system for code Generates the HTML-documentation of your system. Inline comments Keywords Supported by NetBeans
Comment types /* */ Comment area (one or more lines) // Single line comment (rest of the line) /** */ Javadoc Comment (one or more lines)
Keywords A javadoc keyword is used to mark special parts of documentation: @author the author of the class @version the version nr of the class @param a parameter for a method (one keyword per parameter @return the return value of a function @exception the exception thrown
Typical /** * Summary sentence. * More general information about the * program, class, method or variable which * follows the comment, using as many lines * as necessary. * * zero or more tags to specify more specific kinds * of information, such as parameters and return * values for a method */ It is good practice to use the star at the beginning of every line!
Variable description /** * The number of students in the class. * This variable must not be * negative or greater than 200. */ public int numstudents;
/** Method description * Draws an arrow between the two points * given as arguments. * @param point1 the starting point * @param point2 the end point * (arrowhead) */ If the method had returned a value, we would have had a @return tag as well.
Formatting Javadoc can use the basic HTML-tags for simple formatting. <br> line break <p> new paragraph <pre> </pre> preformatted text (
Inline comments A textline initiated by // A textblock surrounded by /* */ Crucial for understanding the code But do not over-comment
What s in a comment? Meaningful and useful information // increase counter two steps first time (why?) Don t write the obvious info, but the thoughts behind. // Add 1 to x (yes, and???) Give the information that is not there already What is the reason for adding? // Don t ask how this works, it does, don t change! I WANT to know! That s why the comment is there // Loop We can probably see that in the code!
Comments /** * This message repaints a warning icon (the badge) over the field given as * parameter. * * @param field the field over which to repaint the icon. */ private void repaintbadge(jcomponent field) { Javadoc Parameter } // First we get the fields location on the screen (!), and convert it to a // point located on this JComponent. // Point p = field.getlocationonscreen(); SwingUtilities.convertPointFromScreen(p, this); // Find out the size of the warning icon and set its position to a point // that is moved slightly for visual appearance. // int x = p.x - warningicon.getwidth() / 2; int y = (int) (p.y + field.getheight() - warningicon.getheight() / 1.5); // Here we call repaint (!), but with a definition of the dirty area, // so that we only paint the icon! // repaint(x, y, warningicon.getwidth(), warningicon.getheight()); Describes the meaning of the code Very little reference to the coded steps and calculations
Comments Should be used with care Should explain what you are doing Not parafrase the algorithm Should clarify the code Can also be too extensive
Your comments Follow good style as described here Add: If a class is co-authored, each method should have a note about the author Important design rationale should go in the class documentation
Further Read the Java Code Conventions! Link on the course home page.