We always write functions or classes and their logic is very complicated. If there is no specification for these structures, later it will be hard for even ourselves to grasp the ideas.
How do you write specifications for complicated functions and classes?
Please tell me something about your own experience, but not just some link, thanks.
On
I see some complaints above about having links to Joel's stuff, rather than inline text, so here is my take on what he is saying.
At the highest levels, functional specifications needs to communicate what the program aims to do to the consumer or customer. I am 100% with Joel on this: the English (well any!) language used with rigour is a very powerful tool that all your customers will be experts at digesting. Experts at UML they ain't.
A top-level functional specification document (FSD) can provide a logical framework that captures the requirements of the system within a logic model that people can understand readily.
Pure requirements documents - something that precedes an FSD - are a tricky fish to deal with. Very few people are able to mentally differentiate what is a requirement and what is part of the solution. So best to keep requirements at a very high level indeed, and, as an analyst, focus on the the FSD.
The FSD should be a complete top-level model of the system, and subsequent design process about fleshing out a hierarchy of models in more detail. The final level of detail is real code.
The FSD should end up a set of simple English statements. Use a single heading level in the documents, keep paras down to two sentences max, and number each para. Review the paras and make sure each one says something useful. If not, delete it. Short is good!
Think very hard about the language in your FSD. Have rigorous definitions of key nouns in your paragraphs. These nouns become your classes. The verbs you use become your class methods. It really is that simple!
As Joel says, write you sentences like you are going to compile them. For example, write "If stuff happens then do more" rather than "If stuff happens, do more" or "do more when stuff happens".
These sorts of written models can benefit from the use of specific diagrams, such as finite state diagrams, but beware of thinking that you can capture a system using a set of UML diagrams. These things just aren't powerful, flexible or rigorous enough to act as a complete description by themselves. It is much more effective to start with an outline written in rigorous English, and supplement that as necessary.
As for the problems of iteration, in an ideal world, you should only need to rework the lower levels of the model. If you have to change the high levels, something serious was wrong. As for UML tools being quicker at enabling revisting - poppy-cock! The key is that all these descriptions are SHORT and CONCISE. English is the way to go, because we have all practiced this for so long.
I've seen people spend an afternoon trying to make the likes of entity diagrams look pretty in terms of overlapping lines. Like why? Is your ultimate solution two-dimension boxes and lines? No! And that's the problem with UML: the diagrams become an end in themselves to the analyst, and cut you off from the customer, rather than aid communication.
I find the biggest challenge with functional specifications is not the format directly, but keeping them in sync with things that drive them (requirements) and things that build upon them (test cases, documentation).
For that reason, I prefer to handle this issue with a model-driven approach rather than a paper-driven one.
I use a UML modeling tool (Enterprise Architect by Sparx Systems, but many tools work as well) to capture all of the artifacts of the project in one place and create traceability between them. In Enterprise Architect, I can create traceability from a requirement artifact to a design artifact (for example) by just putting them both on the same diagram and creating a connector from one to the other with a mouse drag.
My "functional specification" is actually a collection of activity diagrams, one per use case in the system. Each use case ties back to one or more requirements that necessitate that use case. Even end users find it easy enough to follow the activity diagrams and validate them (how easy is it to get end users to read, let alone understand and validate, a traditional, paper-based functional specification?)
In a similar manner, I can create traceability from my activity diagrams (use cases) to specific design artifacts like class diagrams.
QA can model test cases and create traceability from their test cases to the use cases. That way, we see if there are any use cases that do not have test cases (or don't have enough test cases).
The nice thing about Enterprise Architect as a tool is that all of these artifacts are stored in a SQL database, so I can just run some queries that I have built up over time to find artifacts with nothing tracing to/from them.