Develop Reference

What to do after writing the user requirements document?

Suppose I have to develop a Desktop Application using Java SE. I have finished writing User requirements document. In this document, I mentionned the functionnalities of my futur application. I analysed the needs of the user and established What the ideal application has to perform.
Now, I have to conceive the architecture of the application and ddetailled conception of the app. This is what I don't know how to do ?
I have an idea, which is as follow : elaborate a use case diagram, then for every use case, make an sequence diagram finally produce a class diagram from which I can generate the code.
Is this correct ? How about using a database management system at which level I add the use of DBMS ? from the first uml diagramme ?
please any help is a welcome.

Well you know the functions you will implement and you know the requirements. While at this point you should know or infer some database requirements you don't have the whole picture yet. If you want to do an iterative software development you can start with whatever you feel you got more to progress with, then go back to your other tasks and work in increments. Because you are doing an iterative process you will be erasing bits here and there, polishing your work as you go.
To work sequentially, you'd finish all the analysis documentation before doing design, and that before touching code. Initial databases can be generated from java classes (beans), so that's when that comes in.
Under your chosen methodology the wiki link you provided lists what it is expected to be done in order. For the part of high level design, which you claim to have problems with, you'll want the appropriate UML diagrams, use components for modules/software architecture.
Because it is high level design keep it high level, don't delve in details. eg for a videogame: Graphics, Audio, Network, etc, and how they will interact (Interfaces), don't define anything smaller, no classes, no methods, main packages/libraries can be done. For hardware architecture you may use a deployment diagram I guess, have each cube represent the hardware of the boxes that will run your code, you aren't prepared for deployment but you can make changes to your initial proposal next iteration if you need.
Database design is at the end, but the wiki specifically tells you to only define tables, don't define columns yet. You will define that in the low level detail phase.

How Do You Keep UML Diagrams Up To Date?

I am from a Physics background and not a Computer Science background and never did any course at University on class/component diagrams etc and I have never found the need to use them at work.
The main thing that I don't understand is how do you keep them up to date if the code is still being developed or maintained?
e.g. What's to stop me from refactoring several methods or classes and making the class diagram obsolete?
Do you have to constantly update the diagram manually?
I have seen tools that generate UML from the code and these could keep it up to date I suppose but from what I have seen, the auto-generated diagrams don't seem to be useful enough.
Is the UML for a project likely to be created at the start then be left in a documentation folder and gradually get more and more out of date?

I work for a moderately large government agency, so most of our major projects fall into the "Enterprise Java" category. This is what works for us:
Architects model any changes and extensions to our corporate data model using UML diagrams. Generally there will be a conceptual model class diagram, plus a few sequence diagrams that illustrate how the various parts of the system will interact, and maybe a couple of component diagrams.
We have a walkthrough with the business analysts, DBAs and lead developers. This idea of this is to challenge the new model, and agree on changes (there is a lot of "robust" discussion at these sessions). With a good architect, the changes are minimal.
A senior developer creates a technical specification that will typically include a physical database ER diagram based on the architectural model. From the physical model, we automatically generate a database creation script.
The DBAs upgrade the creation script (e.g. Add tablespace and indexspace info) and create/extend the database.
The code gets written. Developers may create their own mini class hierarchies (e.g. POJOs to carry around data). We don't bother to model these in UML as the code should be self-documenting, and changes are inevitable as the code evolves.
Quite often changes will occur during the development phase, especially if using agile methodologies. If these impact on the corporate data model, then the UML and ER diagrams will be updated.
At the end of the project, the documentation is updated to reflect "as built" state.
Getting back to the gist of your question, I'm not a great believer in automated UML <-> code generation. Generally there is data that is personal to the UML diagram (notes, relationship cardinality, sequence diagrams etc) that does not appear in the code or is very difficult to extract. Conversely the code contains stuff (e.g. behavioural method working logic, data structures and caches) that do not necessarily show in the logical UML model. Then there is the whole question of how you map the logical model class hierarchy to database tables...
To summarise, I recommend:
Get the design correct up front. Changes to the logical model are expensive and awkward to implement.
Use a modelling tool that will support all of the artifacts you need from the same data source. That is, the initial UML logical model, the database ER diagram and the database creation SQL DDL. We use Enterprise Architect, but there are lots of other tools that will do this.
Use UML to model the "big picture" and forget it for describing detailed coding. A good rule of thumb is you need UML if any change to the model affects more than just your team. (e.g. A new database field may require a change to the database, a change to a web service, a change to the GUI and a change to a mainframe batch process. UML has a place in defining the data change in a way multiple teams can understand)

Although this is not a question that is normally answered on SO, here's what I've seen and heard:
A project's SW development plan must define how design is being done, and if UML is used, how an update to the SW must be made. That plan can define that the UML is "one shot" - so it is indeed forgotten after the first design progresses into code. OTOH, a strict follow-up rule and ensuing checking may require and guarantee that the UML design is updated during bug fixes (if required) or more extensive changes. (More often than not, you may even have to go back to requirements and update there, too.)
A completely different approach is to generate code from UML - that way you never change the code. Whether this works or not, given the potential differences between UML's expressiveness and what and how a language like Java or C++ provide to implement the semantics of the various diagrams, is a question I'd dearly love to have answered on more reliable data than a salesman's pitch.

As for my experience, class UML diagrams are mostly useless. Generic code changes too often, thus having UML diagrams for it adds too much burden.
Possible exceptions are:
Architecture (component-level) diagrams. Created once, changes rarely, useful for others
Business model. If your application operates on complex model, it may be worth it to generate classes from UML representation. This UML can become quite valuable if you have many applications operating on the same model.
University projects - no comments :-)

It depends on what you choose, what you agree on with the team and stakeholders, what are your priorities, what are your processes and their deliverable artifacts and what are the costs and who will pay them.
As of today there are no production-ready tools or machines to keep the UML documentation up-to-date completely automatically although many are close, e.g. Graphviz + Doxygen to generate UML class diagrams
and many make this task easier, e.g. Sparx Systems's Enterprise Architect or Rapid Quality Systems's Code Rocket
As any other process the UML documentation creation/maintenance is a process that needs to be defined, implemented, managed, optimized (same way as you need to manage experiments in Physics which you already know)
There is a whole website devoted to this topic at Agile Modeling - Effective Practices for Modeling and Documentation

Designing APIs in Java with top-down approach - Is writing up the Javadoc the best starting point?

Whenever I have the need to design an API in Java, I normally start off by opening up my IDE, and creating the packages, classes and interfaces. The method implementations are all dummy, but the javadocs are detailed.
Is this the best way to go about things? I am beginning to feel that the API documentation should be the first to be churned out - even before the first .java file is written up. This has few advantages:
The API designer can complete the design & specification and then split up the implementation among several implementors.
More flexible - change in design does not require one to bounce around among java files looking for the place to edit the javadoc comment.
Are there others who share this opinion? And if so, how do you go about starting off with the API design?
Further, are there any tools out there which might help? Probably even some sort of annotation-based tool which generates documentation and then the skeleton source (kind of like model-to-code generators)? I came across Eclipse PDE API tooling - but this is specific to Eclipse plugin projects. I did not find anything more generic.

For an API (and for many types of problems IMO), a top-down approach for problem partitioning and analysis is the way to go.
However (and this is just my 2c based on my own personal experience, so take it with a grain of salt), focusing on the Javadoc part of it is a good thing to do, but that is still not sufficient, and cannot reliably be the starting point. In fact, that is very implementation oriented. So what happened to the design, the modeling and reasoning that should take place before that (however brief that might be)?
You have to do some sort of modeling to identify the entities (the nouns, roles and verbs) that make up your API. And no matter how "agile" one would like to be, such things cannot be prototyped without having a clear picture of the problem statement (even if it is just a 10K foot view of it.)
The best starting point is to specify what you are trying to implement, or more precisely, what type of problems your API is trying to address. BDD might be of help (more of that below). That is, what is it that your API will provide (datum elements), and to whom, performing what actions (the verbs) and under what conditions (the context). That leads then to identify what entities provide these things and under what roles (interfaces, specifically interfaces with a single, clear role or function, not as catch-all bags of methods). That leads to an analysis on how they are orchestrated together (inheritance, composition, delegation, etc.)
Once you have that, then you might be in a good position to start doing some preliminary Javadoc. Then you can start working on the implementation of those interfaces, of those roles. More Javadoc follows (in addition to other documentation that might not fall within Javadoc .ie. tutorials, how-tos, etc.)
You start your implementation with use cases and verifiable requirements and behavioral descriptions of what each thing should do alone or in collaboration. BDD would be extremely helpful here.
As you work on, you continuously refactor, hopefully by taking some metrics (cyclomatic complexity and some variant of LCOM). These two tell you where you should refactor.
A development of an API should not be inherently different from the development of an application. After all, an API is a utilitarian application for a user (who happens to have a development role.)
As a result, you should not treat API engineering any diferently from general software-intensive application engineering. Use the same practices, tune them according to your needs (which every one who works with software should), and you'll do fine.
Google has been uploading its "Google Tech Talk" video lecture series on youtube for quite some time. One of them is an hour long lecture titled "How To Design A Good API and Why it Matters". You might want to check it out also.
Some links for you that might help:
Google Tech Talk's "Beyond Test Driven Development: Behaviour Driven Development" : http://www.youtube.com/watch?v=XOkHh8zF33o
Behavior Driven Development : http://behaviour-driven.org/
Website Companion to the book "Practical API Design" : http://wiki.apidesign.org/wiki/Main_Page
Going back to the Basics - Structured Design#Cohesion and Coupling : http://en.wikipedia.org/wiki/Structured_Design#Structured_Design

Defining the interface first is the programming-by-contract style of declaring preconditions, postconditions and invariants. I find it combines well with Test-Driven-Development (TDD), because the invariants and postconditions you write first are the behaviours that your tests can check for.
As an aside, it seems the Behaviour-Driven-Development elaboration of TDD seems to have come about because of programmers who did not habitually think of the interface first.

As for my self, I always prefer starting with writing the interfaces along with their documentation and only then start with the implementation.
In the past I took another approach which was starting with the UML and then using the automatic code generation.
The best tool I encountered for this matter was Rational Rose which is not free but I'm sure there are plenty of free plugins and utils.
The advantage of Rational Rose over other designers I bumped into was that you can "attach" the design to your code and then modify on either code or design and the other will update.

I jump right in with the coding with a prototype. Any required interfaces soon pop out at you and you can mould your proto into a final product. Get feedback along the way from whomever is going to be using your API if you can.
There is no 'best way' of approaching API design, do whatever works for you. Domain knowledge also has a large part to play

I'm a great fan of programming to the interface. It forms a contract between the implementors and the users of your code.
Rather than diving straight into code, I usually start with a basic model of my system (UML diagrams etc, depending on the complexity). Not only does this serve as good documentation, it provides a visual clarification of the system structure. Having this makes the coding part much easier to do. This kind of design documentation also makes it easier to understand the system when you come back to it in 6 months, or try to fix bugs :)
Prototyping also has its merits, but be prepared to throw it away and start again.

Code understanding, reverse engineering, best concepts and tools. Java

One of most demanding tasks for any programmer, architect is understanding other's code.
For example, I am contractor, hired to rescue some project very quickly. Fix bugs, plan global refactoring and therefore I need most efficient way to understand the code. What is the list of concepts, their priority and best tools for this?
Of what I know: reverse code engineering to create object models (creating of diagram per package is not so convenient), create sequence diagrams (the tool connects in debug mode to the system and generates diagrams from runtime). Some visualizing techniques, using some tools to work not just with .java but also with e.g. JPA implementors like Hibernate. Generate diagram for not all the codebase, but add some class and then classes used by it.
Is Sparx Enterprise Architect state of the art in reverse engineering or far from that? Any other better tools? Ideally would be that tool makes me understand the code as if I wrote it myself :)

The book Object-Oriented Reengineering Patterns deals with this in detail. Unfortunately there is no silver bullet attached :-)
However, it lists a lot of useful techniques for taking over legacy code. In brief
interview at least some of the original developers (if they are still around) about
development history: phases, releases
current state of affairs
team social structure, politics, dynamics: when and why did people join and leave
bugs: typical, easiest, hardest
code quality: cleanest / ugliest parts
configuration data: form, content and usage
unit / integration / manual / ... test cases and data
SCM branch structure and usage
documentation: what is documented where, is it up to date
contact persons for external interfaces
Watch developers / users during demo to find
main features
typical use cases
usage anecdotes
good / bad, missing / superfluous functionality
"read all the code in one hour"
get high level view of class hierarchies, interfaces
take multiple sessions if needed
identify large structures (these often contain important functionality)
look for design patterns
check comments (they can reveal a lot, but may be also misleading)
skim documentation (if there is any)
just record the availability of specific types of docs e.g. specification, UML diagram, Wiki, Javadoc etc.
is it useful and why (not)
is it up to date

By far the most important tools are your ears, your tongue and your larynx. Ask the people who are familiar with the code - they'll be able to help you understand its general architecture much better than any software tools.
Automatically reverse-engineered complete UML models are generally nearly useless because they cannot distinguish between important abstractions and implementation details - which is the whole point of such models.
Software tools are more useful to answer very specific questions when you are investigating details, such as "where is this method called from?" or "what classes implement this interface" - any good IDE will be able to do that. Debuggers can help too - placing breakpoints at keypoints of the code and looking at the call stack when they're hit is often very enlightening.

Just to elaborate on Michaels mentioning of good IDE's which can help you:
I use the following Eclipse facilities a lot:
Shift-F2 when the cursor is placed in an identifier brings up the Javadoc for that identifier, if any. Good for navigating.
Hovering the mouse over an identifier brings up a box with the Javadoc in it, if any. Good for reminding when writing e.g. a method call.
The Declaration view shows the source where the keyword where the cursor is placed, is defined. This is updated when the cursor moved.
F3 goes to the definition of the current identifier.
Ctrl-T on an identifier shows all subclasses and implementations in a popup. Very useful when working on interfaces.
F4 on an identifier brings up the implementation hierarchy of that identifier in a panel, which can be navigated. Very useful to learn how things are connected. This includes both classes and interfaces.

EclipseUML Omondo is the best Java reverse engineering tool. It reverse all the java code, all packages and even class interaction with interface if not in the same package. Just amazing.
You can also reverse:
- .class
- hibernate annotations
- JPA annotations
What I like with this tool is that my code is clean because all the model information is saved into an xmi format and not as tag in my code. You can also create small documentation inside each existing package using diagrams as a view of the model. Just marvelous and respecting the official uml 2.2 specification.
The only problem is that it is really too expensive so the price is a stop for me !!

Doesn't extract high level architectures, but does make it much easier to climb around your Java code: our Java Source Code Browser. This reads source code (and supporting class files) and produces Javadoc style documentation plus source text bi-directionally hyperlinked to the Javadoc information.
(I'm one of the principals behind it).

I use Enterprise Architect for whole UML (including reverse engineering with Java) and it works perfectly.

Best programming process for creating a graphically-complex Java Swing Application?

I'm starting a fairly complex Swing application that heavily graphics-oriented with about 1000 separate jpegs, 30+ different forms, and timers keeping track of the rate of user-interactions throughout.
My question is from a practical programming perspective, after I've already written a storyboard for the entire project and got it approved by the client, where's the best place (code-wise) to begin programming this massive project and in what order should I program the elements?
(Example Answer: first begin coding the declare and init statements of all the necessary pieces, then write skeleton versions of all the methods, then deal with swing design and layout manager (gridbag), and then deal with Events and Listeners)
Thanks for the advice everyone, oh and btw I really love StackOverflow!

You're describing a "waterfall" development approach - completing some level of the program first, then completing the next level etc. It's indeed one possible approach, but many people find it so called tracer bullet approach better; first make something functional, then learn from it, adjust what's needed and proceed. It's especially useful if you're working with a client, because by showing prototypes you can get feedback and avoid misunderstandings.

I'd pick up a book on TDD and even if you're not going to write automated tests, it will be full of good advice on how to approach your project.
After that I'd pick a single piece of functionality that slices all the way through your application vertically and implement that end-to-end. This should allow you to get any infrastructure/frameworks in place and spot any gotcha's that may get thrown up out of your design.
If your client has the time free, show them each piece of functionality along the way and make sure that every piece you do adds some value to the product.
--EDIT
In addition I'd take a look at using a graphical designer for your screens instead of using the GridBagLayout. That will just waste time and can quickly become a maintainence nightmare when changing screens. I personally prefer the ones that work in a resource file type way, where the screen is essentially "compiled" and you just load it into your code

I prefer writing the UI so, that first I write (using TDD) the backend classes which implement the behaviour of the UI, without any dependencies to the presentation of the UI (i.e. without Swing or any other UI library). After that I write a thin presentation layer with an UI library, where all the event handlers etc. delegate to the UI backend (they should be just one-liners without any logic). The benefit of this is that you can easily write tests for the UI, which in turn makes it easier to change and maintain the UI. See the links at http://martinfowler.com/eaaDev/ModelViewPresenter.html for more details.
At a higher level, first implement the features which will produce the most value to the users. Try to get something to show as early as possible, so that you can get feedback from the users and improve any deficiencies in the UI. You can fake most of the background services (for example the database and business rules), so that the UI can be used, even though it does not yet really do anything.

I think mad-j has the words of wisdom.
Don't concentrate on the 'all'... identify sections/components/modules and deliver those. Then move on to the next and the next. This is called Iterative and Incremental Development (a response to the weaknesses of the waterfall model)!
This will also allow you to create tools and frameworks which should make your development easier and faster as you move along.
This will allow you to show your clients functional parts early. But a word of advice! Your client will more than likely keep changing its requirements, changing the GUI, changing its mind, etc. I've seen entire projects fail due to these continuous changes. It is out of the scope of this question to mention any more on this, but please be aware that it more than likely will happen and be prepared to deal with it!
If you and the client have functional parts, they can be tested immediately rather than testing one huge system.
By completing functional parts iteratively will probably allow you to work at every layer, on most API's using most tools and technologies. The advantage of this is that it will allow you to identify the complexities early. It is those complex areas that render this following statement true:
The first 90% of the code accounts for
the first 90% of the development time.
The remaining 10% of the code accounts
for the other 90% of the development
time. --Tom Cargil
Identifying, acknowledging and understanding those complex areas will allow you to manage your risks and alter your efforts and resources more effectively.
Good Luck,
Jeach!

As mentioned by MrWiggles, you may want to look into using a UI builder.
If you're looking at writing many forms, and it looks like the form data can match nicely to some javabeans, you may want to think about creating some framework panels first.
If you can create some simple base classes that take care of the wiring (syncing the fields to the beans and vice-versa), it'll save you a lot of work.
You may even want to set up some panels that will "auto create" fields based on beans. Just pass in a bean and the panel creates itself. The trick there is specifying layout for the fields, and dealing with fields that have fixed values, validation, etc. (Fixed values can be dealt with using javabean property editors - see http://javadude.com/articles/propedit/index.html.
If you're set on using Swing (eclipse RCP is nice, btw), you might want to look at the Swing Application Framework (https://appframework.dev.java.net/). If not using it directly, it may give you some ideas on how to set up bindings.
Hope this helps a bit

Are you really sure of Swing? Eclipse RCP is much better and flexible starting from EMF and going on
Anyway with Swing, first I'll prepare an XSLT template of all: common code routine and other common pieces of common to bring then them in abstract and interface classes, ORM patterns you use.
Then I'll design a common UI scheme, this "xslize" too.
After all with ANT XSLT processor I'll prepare a complete build procedure upon your specs.
P.S.
I made similar projects for simple web and swing cruds just before 2001, and if you use some peculiar UI designer you can also nest or write with xslt every specs without putting dirty code in your ui raw concepts, so when I make/add remove features on all or singular piece of code, 30 seconds maximum for full rebuild of ALL, of course you must "XSLIZE" all using also many xslt overrider/import.