Last week, we had the author of TDD for a Shopping Website LiveProject. Friday at 11am Ranch time, Steven Solomon will be hosting a live TDD session just for us. See for the agenda and registration link
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Paul Clapham
  • Ron McLeod
  • Jeanne Boyarsky
  • Tim Cooke
Sheriffs:
  • Liutauras Vilda
  • paul wheaton
  • Henry Wong
Saloon Keepers:
  • Tim Moores
  • Tim Holloway
  • Stephan van Hulst
  • Carey Brown
  • Frits Walraven
Bartenders:
  • Piet Souris
  • Himai Minh

Reading Code

 
Ranch Hand
Posts: 1365
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
A writing student's study surely includes a good deal of reading. A music student listens to other musicians. Accordingly, there are methods of attentively/instructively reading and of listening to music. But what about methods for the studying programmer to read and learn from code?

Most programs (Literate Programs aside) have many branches, entry points, and generally non-linear execution paths that prevent a simple cover-to-cover reading process. Some programs come with a few main methods, or perhaps an Ant task, or event GUI integration. Often libraries just provide a large number of classes where there are as many use cases as you can imagine. There are JUnit tests, Servlets and JSPs, Inversion of Control Containers, and a large assortment of other usage patterns. Unlike a book or a recording, there's no set beginning and end.

Question for the JavaRanch community:

What are effective ways to read code? How do you choose what files to examine and in what order? Should you change the code as you read it, and if so when? Perhaps write unit tests for it? What else helps? On a file level should you read a class from top to bottom? Read all method declarations first? Read the instance variable names first? What should you do if there are no javadocs? What can a programmer do to make source code easy to read?

Often at first it seems prudent to find all entry points and start reading code from the top down, following all method calls and branches to see where they lead. In practice, though, I find there are often so many different classes in use that following method calls all over the place is really distracting. On the other hand, not following them can be extremely confusing. Thus I've settled on the practice of reading from the bottom up. I look at class dependencies (import statements and IDEA's "Organize Imports" feature make this easy) and start by reading the classes that don't depend on anything else. I slowly work my way back the dependency chain until I get to the top level. By that time I know what all the method calls mean and I'm less likely to get stuck understanding something.

What techniques do the rest of you find helpful?
[ May 30, 2004: Message edited by: David Weitzman ]
 
Ranch Hand
Posts: 434
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I find that there are two ways to read code;

1: Read the specs for the project (if there are any!) And see if you can match the specs to the different classes.

2: There is always an entry point to a program. Even if there are many entry points, there is a reason for this. I find that reading from the entry points down is best. This way I understand from the higher level what the idea of the code it so that I can get started with changes or debugs from the top down. Then if I need more in depth ideas about the code I read the dependancies.
 
(instanceof Sidekick)
Posts: 8791
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Reading is tremendous exercise. I see way too much code that wasn't read even by the author right after typing it. I try to read almost everything my team writes. The version control tool makes it easy to see the most recent check-ins and even drill into the deltas.

If the code is at all complex, I often scribble almost-UML diagrams - some or all of class hierarchy, interaction, sequence. I might even take the time to clean one of these up, get rid of crossing lines, add some notes, and stick it on the wall for a couple days while I'm getting used to a complex package.

Re finding a starting point - that's much too often the hardest part. You get a package or an API with a whole bunch of classes. Wouldn't it be nice if the package JavaDoc gave you some clue what was going on? When you get back to writing after all this reading, think about other readers and what might help them get started. Boilerplate JavaDoc on get/set methods ain't it.
 
Sunglasses. AKA Coolness prosthetic. This tiny ad doesn't need shades:
free, earth-friendly heat - a kickstarter for putting coin in your pocket while saving the earth
https://coderanch.com/t/751654/free-earth-friendly-heat-kickstarter
reply
    Bookmark Topic Watch Topic
  • New Topic