Skip to main content

Writing it down

Posted by daniel on September 25, 2003 at 7:12 AM PDT

Is documentation part of a class's spec? What belongs in the code and what belongs in the docs?

In Also in Java Today Brian Goetz begins his developerWorks article on Characterizing thread safety by referring to the "Documenting Thread Safety" Item from Joshua Blochs "Effective Java Programming Language Guide"

in which developers are entreated to document in prose exactly what thread safety guarantees are made by the class. This, like most of the advice in Bloch's book, is excellent advice, often repeated, but less often implemented.

So Goetz begins by suggesting that you document thread safety when you write a new class.

The time to document thread safety is definitely when the class is first written -- it is much easier to assess the thread safety requirements and behavior of a class when you are writing it than when you (or someone else) come back to it months later. You'll never have as clear a picture of what's going on in an implementation than you do when you're writing it.

Yesterday we talked about the Gosling interview Failure and Exceptions . Gosling told the following story.

One of the traditional things to screw up in C code is opening a data file to read. It's semi-traditional in the C world to not check the return code, because you just know the file is there, right? So you just open the file and you read it. But someday months from now when your program is in deployment, some system administrator reconfigures files, and the file ends up in the wrong place. Your program goes to open the file. It's not there, and the open call returns you an error code that you never check. You take this file descriptor and slap it into your file descriptor variable. The value happens to be -1, which isn't very useful as a file descriptor, but it's still an integer, right? So you're still happily calling reads. And as far as you can tell, the world is all rosy, except the data just isn't there.

That's the thing about programs. Things change. Traditionally we have had problems making sure that the documentation changes with the code. One solution is to make sure that the documentation is primarily the code itself. The public interface of the class, which includes the exceptions that can be thrown, is one form of documentation. Goetz, however, suggests that we look at things the other way around. Instead of changing the documentation when the code changes (which he would agree needs to be done but often isn't), the documentation might help dictate ways in which the code can change.

Additionally, documenting thread safety guarantees at the time the class is written will increase the chance that future modifications will preserve your initial thread-safety intentions, as maintainers will hopefully see the documentation as part of the class's specification.

We also link to the second article by Ganesh Prasad, Rajat Taneja, and Vikrant Todankar on Web and Enterprise Architecture Design Patterns for J2EE. In this second part the authors present eleven patterns in the Security, Navigation, and Data Volume Control categories.

Joshua Marinacci's Weblog entry Too many ways addresses the recent post by Philip Greenspun that calls Java the SUV of computer languages. Greenspun's post comments on a class assignment where some of his students used Java, some used Microsoft's C#/ASP.NET, some used PHP, and some used JSP. Greenspun's observation is that "A project done in Java will cost 5 times as much, take twice as long, and be harder to maintain than a project done in a scripting language such as PHP or Perl." As an aside, Greenspun's blog has the wonderful subtitle "an interesting idea every three months; a posting every day

Joshua agrees that it does take longer to whip up an application using Java. After wondering whether Java was the right tool for that particular assignment, he asks whether there are too many ways to do things in Java. Join the discussion in the talkback section to his blog.

Craig Castelaz was recently asked Are Encapsulation, Polymorphism, and Inheritance peers? . In his blog entry he ranks encapsulation as the most important and asks what you think.

Today in Projects and Communities, we feature the Java Patterns community that invites you to download a chapter from Real-Time Design Patterns. Wander through the forums in the java.net Java Games community. The Games forums are active and available on a wide variety of topics from available games, to support in developing games, to business related topics.

In today's java.net News Headlines :

Registered users can submit news items for the java.net News Page using our news submission form. All submissions go through an editorial review by news director Steve Mallet before being posted to the site. You can also subscribe to the java.net News RSS feed.

Current and upcoming Java Events:

Registered users can submit event listings for the java.net Events Page using our events submission form. All submissions go through an editorial review before being posted to the site.

This blog is delivered weekdays as the Java Today RSS feed. Once this page is no longer featured as the front page of href="http://today.java.net"> Java Today it will be archived at href="http://today.java.net/today/archive/index_09252003.html">
http://today.java.net/today/archive/index_09252003.html. You can
access other past issues in the java.net Archive.