Code Views - Some Masters Projects
 
The other day a student apologized for the print out of his coding assignment. Another student asked if there was a better way to print out his Smalltalk code. He has spent a lot of time printing his assignment. While some may ask why I have student turn in hard copy, I will delay that for another time. My question is why can’t we print out code and get:
 
  1. • Table of contents
  2. • Project summary
  3. • A reasonable view of each class
 
Instructors and TA would be very grateful for a tool that students could use that did the above.
 
Some Java programmers may point to JavaDoc pages. In 1995 the idea of using Web pages for API documentation was in interesting idea. In 2006 JavaDoc pages suck. Humor me by pretending that JavaDoc pages are really bad. Now spend the next week viewing JavaDoc pages with that mindset to find three ways to improve JavaDoc pages. If your list only has three things on it you did not treat the assignment seriously.
 
I am not concerned here with how to reasonably represent Java’s API in web pages, but how best to present code to help people read and understand the code. Instructors trying to understand student assignments and projects is the motivating example. However programmers read code more often than they write code. Every time a programmer joins a project they are faced with the problem of having to understand a large body of code. Some basic questions are:
 
  1. •What is a good way to present a class to help the reader understand that class?
  2. •What is a reasonable way to present related classes?
  3. •How do present or organize a project to help a new programmer understand the project?
 
If you think that looking at raw source files is reasonable look at Human Factors and Typography for More Readable Programs by Ronald M. Baecker. Keep in mind that the book is 16 years old. Look at  Smalltalk browser view of a class. That idea is about 30 years old. Surely with the high power machines and output devices available we can do better than that.
 
If one goes beyond the idea of producing hard copy of student assignments one finds a lot of different views of code and projects that can be useful in understanding code, projects and their history, but that is another topic.
 
By the way the Smalltalk student should load the advance tools and look at the Class Reporter.
Sunday, April 16, 2006