When I was at university a lecturer said how some people managed to code using sequence diagrams, this to me seems a good way of programming but of course the devil is in the details. I have a few questions.
I've found that "normal" sequence diagrams are almost always more of a pain than they're worth (although I have found them useful for showing data flow in LINQ). Doing a "rough and ready" diagram and explaining it (preferably in person, but with plenty of words either way) works better in my experience.
I think it's a good idea to have a diagram (or several) showing a sort of "vertical slice" of your application - how each layer talks to another, and perhaps showing the course of a request/response in suitable cases. However, this doesn't need to be at the "individual method call and always 100% accurate" level - making sure that you convey the right general impression is more important, assuming the reader can then dive into the real code.
Having said all of this, my views on UML in general are much the same, so if you're a big fan of precise diagrams always being kept meticulously in sync with reality etc, take it all with a pinch of salt :)
I think that sequence diagrams are one of the best ways to visualize complex, multithreaded programs with lots of messages being passed between threads. I don't use them much in design, but sometimes they are the best way to debug.
I've found that sequence diagrams fall short for real applications because:
I can do just well using an outline in English explaining the call hierarchy from layer to layer, when there's a single thread of control. The outline styles in MS Word do just fine here.
My English explanation has more detail and takes up less space than a UML picture.
With English I can explain other details such as guard conditions and loops better than a sequence diagram.
I can write up the outline quicker than drawing up the UML.
If you really need a "picture" with this much detail, perhaps an activity diagram will do the trick.
On the other hand, a sequence diagram is great for a high-level overview.
As far as Java is concerned, my project team really likes Jude as it can reverse engineer a Java 5 codebase's class hierachy.
A sequence diagram will show an interaction, which is typically a single path through your code. Your code, on the other hand, has to define every path, with every if-then-else and edge condition etc. You can show all that stuff on sequence diagrams, but they tend to get much too complex and unwieldy. I would recommend you use sequence diagrams to help visualise your code at the design stage, if that is useful to you, but that is as far as you should probably go.
Sequence diagrams work for procedural languages. They are not as useful for OO languages.
See http://www.reversejava.com for a dynamic reverse engineering application which generates UML Sequence diagram and view of Participating Class diagram from any Java Application at runtime All you have to do is just run your application and sit back. Reverse Java runs in background tracing all the activities happening inside your application and creates UML diagram for you.