 |
BorlandTalk.com
Borland discussion newsgroups
|
| View previous topic :: View next topic |
| Author |
Message |
Paul E. Schoen
Guest
|
 Posted: Sun Jan 22, 2006 11:13 am Post subject: Software specifications |
 |
|
I have finally made a strong effort to make a fairly comprehensive system
specification for my product, which includes some description of the
hardware, but is mostly for the software, which is written in Delphi. I had
started this project essentially with a mental image of its design, as well
as the original version which was an MS-DOS based console application
written in Turbo C and Borland C about 12 years ago. As the new Windows
project grew in complexity, I realized I would be better off with a
specification to work with, and I wrote a preliminary draft about a year
ago, after the program was essentially working but without some of the
extras now in place. Now that I am rewriting much of it in light of what I
have learned recently, I decided I needed a more detailed spec, so I wrote
it. It still needs work, but you can look at the Word document on
www.Ortmaster.com.
I have been frustrated in this project because my software and hardware is
intended to work with a separate application, called TCC, which is
essentially a database program that verifies the results I furnish to it in
a data file. Unfortunately, the original programmer on the project chose
Visual Basic .NET, and he put together essentially an ugly shell of a
program over the period of about a year and then quit. It was taken over by
another programmer who has been my mentor in Delphi, but also adept at VB.
However, the required bug fixes and improvements in that program have been
very slow, and I have begged the distributor of the combined products for a
software specification, and here is what he told me.
"There will be no help or software spec written until we are done, if things
change we may need to rewrite them, why waste time."
The problem is that he has a certain image in mind, and also a previous
simple program he wrote in antique visual Basic for MSDOS, but the
programmer is not familiar with this testing, but I am not supposed to make
suggestions until he is "done". I found 35 or so problems in the software
release I got about 3 weeks ago, and I have seen nothing since then. I could
also vent a bit about the distributor's viewpoints about keeping the
software simple and minimizing keystrokes or mouse clicks by eliminating a
simple message box warning that data was not saved. Apparently, one mouse
click was more important than possibly losing 15 minutes worth of test
results. He looked at it as a time-wasting annoyance in case the technician
really wanted to repeat the test.
Anyway, I seem to be ranting, but I wanted your opinions and personal
experiences with software specifications. I read a number of good articles
by Joel Spolsky ([url]www.JoelOnSoftware.com)[/url], and I agree with much of his
advice. I'm afraid this project is doomed to failure. Customers are asking
me when it will be ready, as they are struggling with old MSDOS software
that gets data through the printer port and won't run on Windows. I know I
could do the entire database project (in Delphi) myself, even having to
learn all about the database functions, in a couple of months or so, from
scratch, but I don't have that option and I might be overestimating my
ability.
Thanks for listening!
--
Paul E. Schoen, President
P S Technology, Inc.
Cockeysville, MD
www.pstech-inc.com
|
|
| Back to top |
|
 |
alanglloyd@aol.com
Guest
|
| Posted: Sun Jan 22, 2006 12:26 pm Post subject: Re: Software specifications |
|
|
In my previous times I worked for a company which designed avionic
systems and wrote software for it. We had a three-level approach ...
1 System specification - this defined what the system did in user
terms.
2 Software specification - this defined how the software worked to
implement the system specifictaion.
3 Program code explanation - this specified exactly what each element
of the code (which implemented the software specification) did & how
it did it.
These were supported by an interface control document which specified
every hardware and software signal and interface in terms of pins,
voltage, resolution, accuracy etc etc.
Now that was for a defence contract with untold money available, but it
is a good structure. You can adjust the level of detail in each element
of the above, but it covers what could be done.
The problem with it is that it defines strictly at each stage, and real
life is not frozen, as ideas for improvement and confirmation of
understandings must arise during the project. It also had strict
control on changes - agreed by all participators.
"Extreme Programming" goes some way to enable definitions in the
presence of improvements to be understood and controlled by shuffling
suggestions and approvals through the stages with some (but not too
much) formality.The stiffness of the definitions depend on whether (and
how much) money and contractual arrangements intrude into the project.
I would be quite worried if people did not agree to some outline
description of what was happening, but it must have some flexibility.
But interfaces to the user and for signals MUST be fairly chilled, even
if not frozen.
I think that with a high level language like Delphi that the code level
explanation can be done by properly commented and transparent code.
Alan Lloyd
|
|
| Back to top |
|
|
Paul E. Schoen
Guest
|
| Posted: Sun Jan 22, 2006 11:50 pm Post subject: Re: Software specifications |
|
|
<alanglloyd (AT) aol (DOT) com> wrote
| Quote: | In my previous times I worked for a company which designed avionic
systems and wrote software for it. We had a three-level approach ...
1 System specification - this defined what the system did in user
terms.
2 Software specification - this defined how the software worked to
implement the system specifictaion.
3 Program code explanation - this specified exactly what each element
of the code (which implemented the software specification) did & how
it did it.
These were supported by an interface control document which specified
every hardware and software signal and interface in terms of pins,
voltage, resolution, accuracy etc etc.
Now that was for a defence contract with untold money available, but it
is a good structure. You can adjust the level of detail in each element
of the above, but it covers what could be done.
|
I appreciate your comments, and agree that controlling documents must be
tailored to the budget and scope of the project. It is more critical to have
greater detail when more people are involved, especially those who are not
fully familiar with the end use of the product.
| Quote: |
The problem with it is that it defines strictly at each stage, and real
life is not frozen, as ideas for improvement and confirmation of
understandings must arise during the project. It also had strict
control on changes - agreed by all participators.
|
That is what I would like to do with this project. My software spec is in
the form of a Word document which can be opened and edited by almost anyone,
and it is available for public access on my website. I could invite all
interested parties, from the top level software distributor to the end users
(who are most important), to read the spec and make comments and
suggestions. I have done that in a limited way for the TCC program, where I
have made a grid with one column for an observed problem or desired feature,
and another column for comments and resolutions. There may be a better way
to keep track of problems and changes, but this is a start. However, I sent
copies to the distributor and the programmer a few weeks ago with no further
reply, so it's not working for that part of the project.
| Quote: |
"Extreme Programming" goes some way to enable definitions in the
presence of improvements to be understood and controlled by shuffling
suggestions and approvals through the stages with some (but not too
much) formality.The stiffness of the definitions depend on whether (and
how much) money and contractual arrangements intrude into the project.
I would be quite worried if people did not agree to some outline
description of what was happening, but it must have some flexibility.
But interfaces to the user and for signals MUST be fairly chilled, even
if not frozen.
That is why I put the screen shots in my specification. Of course, I already |
had the software essentially done, so that was easy, but it is also very
simple to edit a form with whatever controls are obviously needed and fill
in representative data, without actually doing any programming. Once the
overall layout is approved, the underlying code and functionality can be
added, which is usually the hard part.
| Quote: | I think that with a high level language like Delphi that the code level
explanation can be done by properly commented and transparent code.
Yes, that is probably the best place for detailed description of each form |
and control. I am guilty of writing lots of code while an idea is fresh in
my head, and not adding sufficient comments to recall what I was trying to
do when revisiting a few weeks later. I also need to organize my code in a
better way, and would appreciate suggestions. I have some large units that
probably should be broken into smaller functional chunks, and I'm not sure
if it is better to organize functions and procedures alphabetically or in
some other order.
Thanks,
Paul
|
|
| Back to top |
|
|
alanglloyd@aol.com
Guest
|
| Posted: Mon Jan 23, 2006 6:58 am Post subject: Re: Software specifications |
|
|
| Quote: | I'm not sure if it is better to organize functions and procedures alphabetically
or in some other order.
|
I sort my header declarations (in the type clause) alphabetically
within each visibility sub-section. Then in the implementation clause I
order approximately functionally, so that methods associated in a
program function appear together, with general procedures & functions
first, then methods. And within the methods, constructors first, then
property accessors, menu event handlers, then the rest (in functionally
associated groups), with form close handlers at the end and finally
destructors (if I have any).
| Quote: | I have some large units that probably should be broken into smaller functional chunks
|
I don't think it helps to break units down into too small elements.
Class separation will lead the way there. I break code within a unit
down into a separate method/procedure if I use short lengths of code
three or more times, longer lengths of code two or more times. for
multiple code use within one method I use a local sub-procedure.
I have a what may be a slightly ideosyncratic approach to code
arrangement. I believe that the nodes of conditional statements are the
keys to understanding program flow. So "begin(s)" are always in-line
with the conditional, "end(s)" are always commented with the
conditional code (not its description). Long single-statement
conditionals which do not require an "end", have one in a comment.
eg (this should be viewded in fixed pitch font or preferably in Delphi
formatting) ...
if (Users.AllSecList.Count = 0) then begin
{check if secretaries in system}
Msg := 'There are no secretarial services allocated to you' + #13 +
#13 +
'Contact your system administrator to' + #13 +
'add your secretaries before running this program';
Application.MessageBox(PChar(Msg), 'Lexacom Talk', MB_OK or
MB_ICONHAND);
Application.Terminate;
Exit;
end
else
with SecCmbBox do begin
Items.Assign(Users.CurrentUser.SecList);
ValidateSecServices; // check that secservices are valid
{now add e-mail & save-to-disk at bottom}
Items.AddObject('< e-Mail >', TObject(EMailDWdFlag));
Items.AddObject('[ disk ]', TObject(DiskDWdFlag));
ItemIndex := 0; // default secretary is first in list
SecCmbBoxChange(nil); // set SecId, SendBtn.Tag and other items
end; {with SecCmbBox}
{end; if Users.AllSecList.Count = 0 else}
(* I will not participate in a religious war regarding my code style
<g> *)
Alan Lloyd
|
|
| Back to top |
|
|
Hans-Peter Diettrich
Guest
|
| Posted: Mon Jan 23, 2006 10:34 am Post subject: Re: Software specifications |
|
|
[email]alanglloyd (AT) aol (DOT) com[/email] schrieb:
| Quote: | if (Users.AllSecList.Count = 0) then begin
{check if secretaries in system}
Msg := 'There are no secretarial services allocated to you' + #13 +...
|
I prefer to outdent comments as contained in this code snippet, as kind
of "section headers". Often I start coding by inserting the list of
required steps into an procedure body, and fill in the code for every
section later. Then both the coder and the reader of such code will have
a map of what's happening in the following lines of code, up to the next
outdented comment. Using PasDoc or other conventions for marking
comments for automatic processing also may be helpful...
| Quote: | (* I will not participate in a religious war regarding my code style
g> *)
|
Me2, but I'd say that your religion is quite compatible with mine ;-)
DoDi
|
|
| Back to top |
|
|
|
|
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
|
|
FAQ
Search
Memberlist
Usergroups
Register
Profile
Log in to check your private messages
Log in
