[comp.software-eng] Documenting OO Systems

brnstnd@kramden.acf.nyu.edu (Dan Bernstein) (04/12/91)

In article <jls.671247104@rutabaga> jls@rutabaga.Rational.COM (Jim Showalter) writes:
> >I am proud not to be a software engineer.
> See, this is the really interesting thing to me: I cannot think of any other
> technical discipline in which people swagger around bragging about how they
> are not engineers.

Mathematics is a technical discipline. What do you mean to say?

Every working definition of ``engineering'' appears to exclude computer
science. Here's a question: New York State imposes legal requirements
upon anyone working in the recognized fields of engineering. A
``professional engineer,'' for instance, must pass a test in his field
before he can use that title.

What would you put on a test for software engineers?

The existing tests for engineers include some amount of jargon, to be
sure, but they also include *problems* that relate directly to problems
in the *real world*---problems whose solutions are applied directly by
engineers every day. Most of the answers aren't obvious, even to someone
acquainted with the jargon.

So how would you test software engineers?

Would you make sure they knew the latest terminology? Or would you aim
for the blindingly obvious? ``True or false: If you need code ten times,
it is cheaper for the code to be (a) rewritten each time; (b) stored in
a library.''

Or would you use material from what appears to be the vast majority of
software engineering literature---theories that are neither applied by
working programmers, nor proven to help solve *real world* problems.

Maybe there is some engineering behind ``software engineering.'' I'd
love to hear what it is. If you have an example, send me e-mail, and
I'll summarize.

> Would
> anybody even HIRE a person in any other discipline that not only had no
> formal background or credentialization, but was actually PROUD of it?

Be serious. There is a huge difference between someone without formal
training or credentials and someone who is proud not to be a software
engineer.

---Dan

amanda@visix.com (Amanda Walker) (04/13/91)

brnstnd@kramden.acf.nyu.edu (Dan Bernstein) writes:

   Every working definition of ``engineering'' appears to exclude computer
   science.

Indeed.  A large software project is, in my experience, more like a
book than it is like a building.  Do we call novelists "prose
engineers?"  Do we call movie producers "audio-visual entertainment
engineers?"  No, and I don't think we should.  My business card says
"software engineer," and I do what is usually called "software
engineering," but I think that it's a misnomer.  I think that things
like "software author," "algorist," "software designer," "software
artist" (by analogy to "graphic artist" or "commercial artist"), or
"software architect" would be better, but currently they just confuse
people.  People think they know what "software engineer" means.

Part of my problem is that, put simply, I don't think we know enough
about what software is to make it into an engineering discipline or a
trade.  Software is so mutable and responsive that I can't think of
its creation and manipulation as anything except an artistic
disclipline.

When I interview someone I'm interested in hiring, I'd rather see
a portfolio of their work than what certificates they've earned.


--
Amanda Walker						      amanda@visix.com
Visix Software Inc.					...!uunet!visix!amanda
-- 
"In all my life, I have prayed but one prayer: 'O Lord, make my enemies
 ridiculous.'  And God granted it."	--Voltaire

jls@rutabaga.Rational.COM (Jim Showalter) (04/13/91)

>Every working definition of ``engineering'' appears to exclude computer
>science.

Is this something to be PROUD of? As it stands, it is certainly an
accurate reflection of the current state of affairs, but hardly
a good thing.

>What would you put on a test for software engineers?

What do they put on tests for other engineers?

>The existing tests for engineers include some amount of jargon, to be
>sure, but they also include *problems* that relate directly to problems
>in the *real world*---problems whose solutions are applied directly by
>engineers every day. Most of the answers aren't obvious, even to someone
>acquainted with the jargon.

I'm a bit confused. Is it your belief that software engineers do NOT
work on problems directly related to the real world? I thought that
satellites, dishwashers, dialysis machines, airplanes, telecommunications
equipment, laptop computers, relational databases, finite element analysis
models, and, well, actually, every OTHER thing I've seen software
used for was part of the real world.

Or did you mean to say something other than what you appear to be saying?

>Would you make sure they knew the latest terminology? Or would you aim
>for the blindingly obvious? ``True or false: If you need code ten times,
>it is cheaper for the code to be (a) rewritten each time; (b) stored in
>a library.''

I think I'd ask them to solve some problems. Probably have them rig
up an interface to some device, write some queries for a database,
reverse engineer a design from some legacy code, etc etc etc. You
know--do some software engineering.

Think of it as the kind of thing lawyers have to do to pass the bar,
or doctors have to do to become doctors.

>Or would you use material from what appears to be the vast majority of
>software engineering literature---theories that are neither applied by
>working programmers, nor proven to help solve *real world* problems.

Could you please list some software engineering theories that are
not applied by programmers and/or do not help to solve real world
problems? For extra credit, could you give me an example of a real
world problem? I think we have some sort of communications problem.
--
* The opinions expressed herein are my own, except in the realm of software *
* engineering, in which case I borrowed them from incredibly smart people.  *
*                                                                           *
* Rational: cutting-edge software engineering technology and services.      *

cok@islsun.Kodak.COM (David Cok) (04/14/91)

In article <1991Apr12.201053.18348@visix.com> amanda@visix.com (Amanda Walker) writes:
>Indeed.  A large software project is, in my experience, more like a
>book than it is like a building.  Do we call novelists "prose ...

A publisher friend once said to me that books were never finished, only
abandoned, meaning that they were declared complete when the author tired
of correcting and improving.  Another similarity between books and software...

David R. Cok
Eastman Kodak Company
cok@Kodak.COM

brnstnd@kramden.acf.nyu.edu (Dan Bernstein) (04/14/91)

In article <jls.671514765@rutabaga> jls@rutabaga.Rational.COM (Jim Showalter) writes:
> >The existing tests for engineers include some amount of jargon, to be
> >sure, but they also include *problems* that relate directly to problems
> >in the *real world*---problems whose solutions are applied directly by
> >engineers every day. Most of the answers aren't obvious, even to someone
> >acquainted with the jargon.
> I'm a bit confused. Is it your belief that software engineers do NOT
> work on problems directly related to the real world?

The key phrases are ``problems whose solutions are applied directly by
engineers every day'' and ``most of the answers aren't obvious.''

> I think I'd ask them to solve some problems. Probably have them rig
> up an interface to some device, write some queries for a database,
> reverse engineer a design from some legacy code, etc etc etc. You
> know--do some software engineering.

That sure sounds like a programming test to me. You wouldn't find people
doing ``software engineering'' to produce correct answers on that test.
Are you saying that any working program is the result of software
engineering? That's an extremely broad definition.

How come you can only come up with test problems, not questions? Is
there no significant body of nontrivial ``software engineering''
techniques that you can test someone's knowledge of? The electrical
engineering tests don't ask you to build a computer.

---Dan

steve@Advansoft.COM (Steve Savitzky) (04/16/91)

In article <1991Apr12.201053.18348@visix.com> amanda@visix.com (Amanda Walker) writes:

  brnstnd@kramden.acf.nyu.edu (Dan Bernstein) writes:

     Every working definition of ``engineering'' appears to exclude computer
     science.

  Indeed.  A large software project is, in my experience, more like a
  book than it is like a building.  Do we call novelists "prose
  engineers?"  Do we call movie producers "audio-visual entertainment
  engineers?"  No, and I don't think we should.  My business card says
  "software engineer," and I do what is usually called "software
  engineering," but I think that it's a misnomer. 

The tax return for my at-home-on-the-side business says "author"; I
write software, prose, and songs, and find that the three activities
are more similar than different.  Perhaps we should start borrowing
our terminology from the arts: "producer" for the person who puts up
the money and controls the budget, "director" for the one with overall
artistic control, "designer" for the one who creates the look and feel
of the project, and "writer" for the ones doing the programming and
the technical writing (hopefully mostly the same people).

  Part of my problem is that, put simply, I don't think we know enough
  about what software is to make it into an engineering discipline or a
  trade.  Software is so mutable and responsive that I can't think of
  its creation and manipulation as anything except an artistic
  disclipline.

I think Knuth was absolutely right when he called his book "The Art of
Computer Programming".  It's possible to treat software as a product
of engineering only when it's embedded in a non-interactive system.
As soon as the software has a user interface, artistic considerations
take over.
--
\ --Steve Savitzky--  \ ADVANsoft Research Corp \ REAL hackers use an AXE! \
 \ steve@advansoft.COM \ 4301 Great America Pkwy \ #include<disclaimer.h>   \
  \ arc!steve@apple.COM \ Santa Clara, CA 95954   \        408-727-3357      \
   \__ steve@arc.UUCP _________________________________________________________

schwartz@groucho.cs.psu.edu (Scott Schwartz) (04/16/91)

steve@Advansoft.COM (Steve Savitzky) writes:
   Perhaps we should start borrowing our terminology from the arts...

Look at the credits on a video game sometime.  They are usually phrased
as you suggest.

cole@farmhand.rtp.dg.com (Bill Cole) (04/16/91)

Steve Savitzky writes: 
|>      Every working definition of ``engineering'' appears to exclude computer
|>      science.
|>  
|> I think Knuth was absolutely right when he called his book "The Art of
|> Computer Programming".  It's possible to treat software as a product
|> of engineering only when it's embedded in a non-interactive system.
|> As soon as the software has a user interface, artistic considerations
|> take over.
|>

I'd extend that to any user interface -- including reports.  Someone will
spend time (maybe hours) with the reports we generate and 'readability'
is a definite factor in how we format and produce the report.

Programming is a creative endeavor at some level.  We have to devise
ways to overcome obstacles placed in our paths by an EE or another
programmer.  Many times, the solution to a problem is nothing short of
the 'eureka' moment, that golden moment of insight that brings an
unexpected fix to a difficult problem.  If we were strictly engineers,
we could down a catalog of routines and, by cleverly sticking them
together, build a program.  Each programmer has a catalog of routines
they've either learned or built, it's true, and you could argue that
this constitutes a form of engineering catalog that EEs or CEs use to 
build computers or buildings.  The difference is that programmers are
tasked to build new components if they can't find one in the own catalog
of program components.  How many CEs build bridges out of self-designed
components?  

The views expressed here are opinions formulated for and by myself,
/Bill

jeff@hilbert.uucp (Jeff Freedman) (04/18/91)

In article <STEVE.91Apr15150739@diana.Advansoft.COM> steve@Advansoft.COM (Steve Savitzky) writes:
>  brnstnd@kramden.acf.nyu.edu (Dan Bernstein) writes:

>  book than it is like a building.  Do we call novelists "prose
>  engineers?"  Do we call movie producers "audio-visual entertainment
>  engineers?"  No, and I don't think we should.  My business card says

Note also that we don't call a person a novelist unless he or she has
actually written a book, but it seems that there are quite a few "experienced
software engineers" running around who couldn't write an ounce (at 1K byte/oz.)
of software.  I'd like to believe that the best software being written
nowadays is at companies where the programmers are considered to be authors,
rather than engineers; and that they are judged by their ability to design and
write code, rather than their ability to spout jargon and write memos.

-- Jeff Freedman

jrj1047@ritvax.isc.rit.edu (JARRETT, JR) (04/18/91)

In article <1991Apr16.124522.16592@dg-rtp.dg.com>, cole@farmhand.rtp.dg.com 
(Bill Cole) writes...
>|> I think Knuth was absolutely right when he called his book "The Art of
>|> Computer Programming".  <stuff deleted>
> 
> If we were strictly engineers,
>we could down a catalog of routines and, by cleverly sticking them
>together, build a program.  Each programmer has a catalog of routines
>they've either learned or built, it's true, and you could argue that
>this constitutes a form of engineering catalog that EEs or CEs use to 
>build computers or buildings.  The difference is that programmers are
>tasked to build new components if they can't find one in the own catalog
>of program components.  How many CEs build bridges out of self-designed
>components?  
>                             

Thinking of software development more as art than engineering, this process
seems more akin to working out different brush strokes on canvas, or 
mastering different styles of writing.  They work, unmodified in a lot of
cases, but sometimes need to change.

rick@tetrauk.UUCP (Rick Jones) (04/18/91)

In article <1991Apr16.124522.16592@dg-rtp.dg.com>
		cole@farmhand.rtp.dg.com (Bill Cole) writes:
>
> [...] Many times, the solution to a problem is nothing short of
>the 'eureka' moment, that golden moment of insight that brings an
>unexpected fix to a difficult problem.  If we were strictly engineers,
>we could down a catalog of routines and, by cleverly sticking them
>together, build a program.  Each programmer has a catalog of routines
>they've either learned or built, it's true, and you could argue that
>this constitutes a form of engineering catalog that EEs or CEs use to 
>build computers or buildings.  The difference is that programmers are
>tasked to build new components if they can't find one in the own catalog
>of program components.  How many CEs build bridges out of self-designed
>components?  

I think all fields of engineering require a measure of creativity to be
successful, it's not exclusive to sofware engineering.  Thinking of
auto-engineering, there are a number of landmark innovative cars which changed
the rule book - the VW beetle and Alec Issigonis' Mini are just two examples.
These cars weren't made by assembling all the standard bits from the catalogue;
they were the result of saying "why not do it like this instead? - I don't care
if it hasn't been done before!".  The _engineering_ is then applying the
knowledge of the underlying science - calculating stresses, etc - so that the
new components for the new design can be built.  This is what pioneers do;  the
followers then copy the ideas, and use these new components, or more likely the
component _designs_, to build the copies.  Soon the new bits are part of the
standard catalogue.

Engineers in all disciplines can and do come up with novel designs, and if the
components for what they want don't exist, they build them.  Perhaps the
difference is that they look for existing components first, and resort to
building them only if they don't already exist.  But more significantly, even
if they do build their own components, in most cases they will use standard
_designs_ to build them from.

Software at all levels is a design process, _not_ a production process.  So the
magical notion of "reuse" is a reuse of design, which may or may not exist in
the form of actual compilable source code.  Which brings us full circle - the
most important aspect of technical software documentation, OO or otherwise, is
the description of the design principles of the module rather than the actual
implementation mechanism.

-- 
Rick Jones, Tetra Ltd.  Maidenhead, Berks, UK
rick@tetrauk.uucp

Any fool can provide a solution - the problem is to understand the problem

bw@uecok.ecok.edu (Bill Walker CS Dept. Chairman) (04/19/91)

	Re: definition of "software engineering".

	I had opportunity to have lunch with several 
	prominent computer scientists (whose names I believe
	most folks would recognize.)  

	The conversation can be summarized like this:

		Prof A:  What is "software engineering"?

		Prof B:  The study of large programs.

		Prof A:  What is a large program ?

		Prof C:  Any program we do not understand.

		Prof A:  By this logic, software engineering
			is the study of programs we do not
			understand.  How do we escape this 
			dilemma ?

		Prof D:  "Don't call it 'software engineering!'"


Bill Walker
bw@cs.ecok.edu

diamond@jit345.swstokyo.dec.com (Norman Diamond) (04/19/91)

In article <764@uecok.ECOK.EDU> bw@uecok.ecok.edu (Bill Walker CS Dept. Chairman) writes:
>		Prof A:  What is "software engineering"?
>		Prof B:  The study of large programs.
>		Prof A:  What is a large program ?
>		Prof C:  Any program we do not understand.
>		Prof A:  By this logic, software engineering
>			is the study of programs we do not
>			understand.  How do we escape this 
>			dilemma ?
>		Prof D:  "Don't call it 'software engineering!'"

Wrong conclusion, I think.  Engineering IS (partly) the study of
situations that are incompletely understood.  If a bridge will be
a clone of an existing bridge (if it were possible to know that
without having to do any studies to change unknown information
into known information), then there will be no engineering work
involved.  If the conditions are slightly different from anywhere
else, if study has to be done to understand the exact situation
and to decide which scientific laws to apply to each part of the
problem, that is engineering.
--
Norman Diamond       diamond@tkov50.enet.dec.com
If this were the company's opinion, I wouldn't be allowed to post it.

kitchel@iuvax.cs.indiana.edu (Sid Kitchel) (04/19/91)

diamond@jit345.swstokyo.dec.com (Norman Diamond) writes:

|->Wrong conclusion, I think.  Engineering IS (partly) the study of
|->situations that are incompletely understood.  If a bridge will be
|->a clone of an existing bridge (if it were possible to know that
|->without having to do any studies to change unknown information
|->into known information), then there will be no engineering work
|->involved.  If the conditions are slightly different from anywhere
|->else, if study has to be done to understand the exact situation
|->and to decide which scientific laws to apply to each part of the
|->problem, that is engineering.

	Yep!! This is the Engineering School party line: engineering is
the application of scientific law to practical problems. This (rather
modern) definition of engineering is the basis for many REAL engineers
being curious or critical of the use of "software engineer" as a title.
But being argumentative and a reformed historian of science, I am forced
to point out that engineering existed and succeeded long before Galileo
and other Renaissance types invented the scientific study of strength of
materials. Those many miles of Roman aquaduct still functioning in France
and Spain do not know that the engineers that built them missed the 4 or
5 years at Purdue or MIT. Those Roman engineers succeeded without having
"to decide which scientific laws to apply." Software engineers may well
be succeeding before computer science grows out of its bastardized
mathematics phase and also becomes a science. Software engineering may
succeed without the full blessing of all academic computer scientists or
institutionalized engineers. But the job it is trying to do is very tough
and it may well not succeed. Only time and experience will tell, just as
in science.
					Now back to parallelizing databases,
							--Sid

-- 
Sid Kitchel...............WARNING: allergic to smileys and hearts....
Computer Science Dept.                         kitchel@cs.indiana.edu
Indiana University                              kitchel@iubacs.BITNET
Bloomington, Indiana  47405-4101........................(812)855-9226

styri@cs.hw.ac.uk (Yu No Hoo) (04/22/91)

<somebody> wrote:
>      Every working definition of ``engineering'' appears to exclude computer
>      science.

I really don't know. Isn't this statement kind of ... conclusive? I don't
it's a true statement.

In article <1991Apr16.124522.16592@dg-rtp.dg.com> cole@farmhand.rtp.dg.com (Bill Cole) writes:
>
>                      [...]             If we were strictly engineers,
>we could down a catalog of routines and, by cleverly sticking them
>together, build a program.  Each programmer has a catalog of routines
>they've either learned or built, it's true, and you could argue that
>this constitutes a form of engineering catalog that EEs or CEs use to 
>build computers or buildings.  The difference is that programmers are
>tasked to build new components if they can't find one in the own catalog
>of program components.  How many CEs build bridges out of self-designed
>components?

I guess there are some CEs out there that would be offended by the above
statement. If the last sentence was rewritten to the EE domain it would
be equally untrue. Even if the statement was true it implies a very
narrow definition of engineering. Maybe we need to define the words
'engineer' and 'engineering' before claiming that 'software engineering'
is a contradiction.

A very important part of an engineers work is to transform plans/requirements
to product in a systematic manner. I see no reason for excluding the software
engineer at this point. To be able to do his/her work the engineer must be
able to communicate both wih fellow engineers and people from other professions.
This is also true for the software engineer. However, software engineers do
have a problem when it comes to standards and metrics.

It's my personal opinion that producing software should be no different
from producing cars. But state of art in software engineering is probably
pre-Ford compared to the car industry.

----------------------
Haakon Styri
Dept. of Comp. Sci.              ARPA: styri@cs.hw.ac.uk
Heriot-Watt University          X-400: C=gb;PRMD=uk.ac;O=hw;OU=cs;S=styri
Edinburgh, Scotland

jls@rutabaga.Rational.COM (Jim Showalter) (04/23/91)

>> If we were strictly engineers,
>>we could down a catalog of routines and, by cleverly sticking them
>>together, build a program.

Isn't that what we DO? We gather together small chunks (e.g. various
library routines) and big chunks (e.g. X-Windows), and paste together
a system. At least, that's what a software engineer does--I've known
a lot of hackers who want to start from a blank sheet of paper each time...

>>The difference is that programmers are
>>tasked to build new components if they can't find one in the own catalog
>>of program components.

As are all other engineers. Consider four-wheel steering. It didn't exist
until a few years ago. Someone had to design it. It was built out of as
many low-level units as possible (e.g. universal joints), but it was still
a brand-new mechanism for automobiles. I can think of examples for any
engineering discipline you'd care to name.

>How many CEs build bridges out of self-designed
>>components?  

If bridges are not very creative avenues for civil engineers, it is because
civil engineering is a more mature discipline than software engineering. It
is NOT because there is some fundamental difference between the two. Consider
this: until the 1800's, HALF of all bridges built fell down. Why? Because the
principles of civil engineering were not well-understood, and so much of it
was empirical and artistic: more craft than science. It is different now, but
I bet for a while there were members of the old guard who protested loudly
that civil engineering was not a science and never could be...just like hackers
proclaim loudly now.
--
* The opinions expressed herein are my own, except in the realm of software *
* engineering, in which case I borrowed them from incredibly smart people.  *
*                                                                           *
* Rational: cutting-edge software engineering technology and services.      *

kambic@iccgcc.decnet.ab.com (George X. Kambic, Allen-Bradley Inc.) (04/26/91)

In article <1991Apr17.175106.5581@hilbert.uucp>, jeff@hilbert.uucp (Jeff Freedman) writes:
> In article <STEVE.91Apr15150739@diana.Advansoft.COM> steve@Advansoft.COM (Steve Savitzky) writes:
>>  brnstnd@kramden.acf.nyu.edu (Dan Bernstein) writes:
>I'd like to believe that the best software being written
> nowadays is at companies where the programmers are considered to be authors,
> rather than engineers; and that they are judged by their ability to design and
> write code, rather than their ability to spout jargon and write memos.

Novels have critics and readers with opinions.  Software must unequivocally
meet requirements at some point or it "don't fly".  You need engineers for
that.

GXKambic
standard disclaimer

jeff@hilbert.uucp (Jeff Freedman) (04/28/91)

In article <4365.2816ec94@iccgcc.decnet.ab.com> kambic@iccgcc.decnet.ab.com (George X. Kambic, Allen-Bradley Inc.) writes:
>Novels have critics and readers with opinions.  Software must unequivocally
>meet requirements at some point or it "don't fly".  You need engineers for
>that.

Much software also has critics and users with opinions.  And novels do have
to meet some requirements, such as decent grammar and coherency.  Perhaps
we're arguing from different ends of the industry.  I would probably agree
that the embedded software controlling an anti-lock braking system is closer
to "engineering", while a fantasy roll-playing game is closer to "art".

-- Jeff Freedman

kambic@iccgcc.decnet.ab.com (George X. Kambic, Allen-Bradley Inc.) (04/30/91)

In article <1991Apr27.231303.14133@hilbert.uucp>, jeff@hilbert.uucp (Jeff Freedman) writes:
> In article <4365.2816ec94@iccgcc.decnet.ab.com> kambic@iccgcc.decnet.ab.com (George X. Kambic, Allen-Bradley Inc.) writes:
> Much software also has critics and users with opinions.  And novels do have
> to meet some requirements, such as decent grammar and coherency.  Perhaps
> we're arguing from different ends of the industry.  I would probably agree
> that the embedded software controlling an anti-lock braking system is closer
> to "engineering", while a fantasy roll-playing game is closer to "art".

Maybe we are, but without being too far apart I think.  Novels and bridges 
do not appear to be adequate models to explore these issues.  

Since I have spent a lot of time testing software, I am very concerned about 
its robustness and error tolerance under any circumstances.  I want that 
sucker to work and be easily repairable in the maintenance life cycle.  BUT, 
it must have the quality factors of usability, etc., that make customers 
salivate when it is demonstrated to them so they buy right then and there.  

Fundamentally the process is a continuum wherein each person involved in
the creation must respect the opinion of others who are also
involved.  Each segment, marketing, sales, engineering, is fundamentallu 
responsible for measuring their part of the process and improving it.  This 
includes, if you will, "artistic" influences that may form the external 
appearance of the HMI.  A word appeared recently in another context that is 
applicable, and that word is discipline.  There are many disciplines required 
of us to properly manufacture software.  There is no one sole source of 
knowledge or ideas for making the product better.  Also, self discipline 
is required; that discipline that makes each one of us do the finest work 
possible, measure its quality, self criticize it, and start
again.  

GXKambic
No time to think up a stunning disclaimer