Absolute Minimum Requirements for Good Software Design

Question

I am trying to write a spec for a software application. The application takes inputs from static files (configuration data), files that it obtained by ftp, and "live" data obtained via a TCP socket. It does some stuff and generates output data, which is delivered to somebody else via a TCP socket.

It is not so difficult to write a spec describing what the system should do when nothing goes wrong and even describing what it should do when certain things go wrong.

But recent experience has told me that it might be a good idea to include explicitly what some people might call "no-brainers". Like keep the user-configurable data separate from the software, so when an upgrade is installed, it doesn't clobber the user data. Or have user-configurable levels of error logging. Things like that.

Does anyone have a list of basic requirements that they would want any system to have and that any decent software developer would do more or less automatically?

Answer 1

Testability: If you make your design testable, everything else will fall in line.

Answer 2

decent logging. it's easier to pin-point issues and goes a long way in maintaining the app.

edit: i mean it should be a part of the design, not an afterthought. logging is a v. costly operation and shouldn't be too frequent.

Answer 3

My two biggest questions:

1) How should the application be packaged? What are the OS's conventions for config files, data files, documentation, and so on? What about installers? Packages?

This is important, because it will usually suggest (and answer) a whole bunch of other important questions for me. On a typical Linux distribution, for example, configuration files should be stored in /etc, log files should be managed with logrotate, and daemons should be managed using init scripts. I get answers to all the questions without having to remember everything myself.

2) Does this application need to deal with Unicode? Most applications do, these days. But you'll never having working Unicode support unless you write the necessary test cases.

Answer 4

I would agree with your idea not to make any undocumented assumptions (what you're calling 'no-brainers') if you're planning to outsource the development (i.e. when writing for people who you don't know). They may have quite different background and a quite different set of assumptions. Even if you DO know your development team it is always useful to document the assumptions at the start of specification document (or even better in the project Wiki) so they could always be reviewed by the team.

The rest really depends on the software development methodology you adopt. If you work in Agile mode you could leave quite a lot of specific things out of your spec and discuss later with the team.

If you are in a higly formal environment you might start with playing with things like UML Activity Diagrams as they will help you identifying problematic parts and will give you a good understanding of what should be documented in more details in the spec.

Answer 5

In my dev groups, we've always had coding standards documents, but they usually talk more about coding style, not baseline technical requirements. I can see the benefit of such a document however, especially if you have a number of small projects on-going, with little overlap between developers and projects. Baseline technical requirements would help maintain continuity from one project to the next.

• Library/namespace naming conventions
• Log-file output locations, naming, roll-over frequency, etc. (including Windows Event Log entry naming)
• Localization conventions
• "Live" help, context sensitive help, etc.
• For database-applications, SQL standards (table naming, stored procedure naming, etc.)
• All the code-style stuff (indention/whitespace, comments, variable naming, etc.)
• Performance counter naming conventions

So yeah... looking back at my quick list, a lot of it has to do with normalization of naming conventions.