Code Reading in Eclipse

It’s rare that a programming task actually involves creating an entire new program from scratch. We spend much more of our time modifying older programs to add features, fix bugs, or improve performance.

Even if we are writing an entirely new application, we aren’t likely to be writing all the libraries that it will use. Everything from data structures to I/O is probably being pulled from one or more libraries.

What this adds up to is the realization that programmers spend much of their time reading other people’s code (or code of their own that they have not seen in so long that it might as well have been written by someone else). It’s crucial to get yourself quickly to a point where you understand enough about the existing relevant code base to know what you can use and how to use it.

There’s two aspects to this. One is that you need to be able to read and navigate other people’s code. The second is that you prepare the way for readers by giving appropriate documentation in the way that they expect to see it.

We’re going to pretend, whether it’s true of not, that you finished the one of the previous labs on the Pie project, then went away for a long weekend, returned on Monday morning, opened Eclipse to that project, and immediately said to yourself, “What in the world is all this?”

When reading unfamiliar code, programmers will continually be asking “What is this symbol?”, “What does it mean?”, “What can I do with it”, and “What will I break in this program if I change it?”. We’ve already seen how Eclipse helps suggest things that you can do with symbols. Now we’ll look at some of the other facilities that it provides for improving your understanding.

1. Open Eclipse and return to the Pie project.

2. Open PieSlicer.java in the editor. Scroll down towards the bottom of that file and look for the line that says

   pv.repaint();
   

   Let’s suppose that you were convinced that this line was significant, but had no clue what it was doing. After clicking anywhere in the editor pane, just let your mouse hover for a few seconds over the word “repaint”. The documentation for that function pops up for you.

3. OK, so now you know what the function is supposed to do. What about that variable “pv”? Try hovering over that. Not so helpful this time, right?

   Double click on “pv” to select the entire word. Hit F3 or choose “Open Declaration” from the Navigate menu. You will be taken to the place where pv was declared. Now we can at least see that pv is a data member of the PieSlicer class. We can see that its data type is PieView. But what’s a PieView? Hover over the word “PieView” and the documentation pops up. Want more details? Select the word “PieView” and hit F3 again. Now you’re taken to the file and the line where PieView is declared.

4. Go back to PieSlicer.java. Just above the declaration of pv, add a comment explaining what it is, so that the end result looks like this:

   /**
   * The panel containing our pie.
   */
   PieView pv;
   

   Save the file.

   Now look a few lines down below where you can see some code that manipulates pv. Hover your mouse over one of those occurrences of “pv” and look at the documentation that pops up. Look familiar?

   Eclipse’s ability to show you documentation is not magic. It’s just showing you information derived from the location of the declaration plus any immediately preceding block of comments that begin with a “/**” instead of the more basic “/*”.

5. The F3/Open Declaration code let’s you move backwards from places where symbols are used to where they are declared. You can also move in the other direction, allowing you to explore the possible implications of any changes you might want to make.

   Open Pie.java in the editor. Look through the data members at the top of the class and double-click on “sliceAngle” to select it. Let’s find out what parts of the program would likely be affected if we were to make changes to this data member. Hit Ctrl-Shift-G or select “Search…References…Workspace”. At the bottom of the window, in the Search tab, you can see that you are told that there are 4 references to sliceAngle in your workspace.

   Scrolling down within that tab, you can see that some of these references occur within the class Pie and other within PieView. Double click on each reference listed to view it in the editor.

   With this technique, you can quickly estimate what code would be broken, affected, or would need to be rewritten if you were to make a change to any data or function members.

6. So far, our exercises in code reading have been focused upon specific items. Sometimes, you want more of an overview. The Java JDK comes with a documentation tool, javadoc, which can be easily launched from within Eclipse. This tool generates a set of interlinked web pages based upon the overall structure of your project and upon the “/**”-style comments that you have provided.

   From the Project menu, select “Generate javadoc”. Make sure that the Pie project is selected. If desired, you can change the Destination directory (the default is to create a “doc” directory within your project. Click Next. On the next page, click the “Select All” button, then click Finish.

   A collection of web pages is generated. View these, starting with index.html, with a web browser (use the File->Open menu entry of almost any browser to view files directly that are not available on a web server). You can probably do this easily from the Package browser by expanding the doc directory, right-clicking on index.html, and selecting “Open With” either “web browser” to view the files within Eclipse or “system editor” to launch the default browser in a separate window. Take a look at each of the 4 classes. Notice how the “/**” comments have been rendered into the web page documentation.

   In one sense, there’s no information here that you could not have obtained by reading the code. But it’s all the automatically generated links that make these web pages particularly nice. For example, look at PieView. In the “Method Summary”, you can see both function members of the PieView class. For the first one, getPie(), there are links on both “Pie” and “getPie”. The first link takes you to the documentation for the return type of this function (Pie). The second like takes you to the detailed documentation of the getPie() function.

7. Look at the info for the PieView paint function. This takes a parameter of type “Graphics”, which is a link. Click on that for information. You’re now looking at documentation from the Oracle Java website. You can confirm this by right-clicking in the Graphics documentation and selecting your browser’s option to view info about the frame (not the entire page), or you can click the “noframes” link at the top and observe the URL of the unframed page. javadoc has actually integrated links to the official Oracle documentation all throughout your project documentation, We requested this interlinked info when clicking on the “Select All” button earlier.

8. Exit Eclipse.