How to write a functional specification?

Question

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.

Answer 1

Check out Joel on Software. And here. And here. There's even a real-world example.

Answer 2

http://en.wikipedia.org/wiki/Functional_specification

See the related links.

Also, ArgoUML (or any UML modeler) can help create visual diagrams that you can include in the specifications.

Answer 3

You should make on research on the following subjects (not necessarily in order):

• UML
• SSD
• Use Cases
• Activity Diagrams

These are the most common approaches for software projects specification.

Answer 4

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.