Re: Hungarian notation

Re: Hungarian notation

[Roger Merritt]

Franz.Kruse@erno.de (Franz Kruse) wrote:


>Could someone please post an article describing Hungarian Notation in some detail
>and giving examples?

>Thanks,

>Franz

If you can get the book Code Complete from Microsoft Press (can't
remember the author) he describes the coding method in detail. It was
devised by a super-programmer at Microsoft (originally at PARC) named
Semonyi (if my memory is correct) who was Hungarian.

The idea is that you include information in the name of the variable
to help you remember the type. So a pointer to a char might be named
cpCurrent.

Same thing applies to function names to help you remember the type
returned.

The book I mentioned is a fairly good one on the methodology of
designing software, but I thought it was far too long and contained
far too few code examples.

Re: Hungarian notation

[Keith Whittingham]

Roger Merritt wrote:
> 
> Franz.Kruse@erno.de (Franz Kruse) wrote:
> 
> >Could someone please post an article describing Hungarian Notation in some detail
> >and giving examples?
> 
> >Thanks,
> 
> >Franz
> 
> The idea is that you include information in the name of the variable
> to help you remember the type. So a pointer to a char might be named
> cpCurrent.
> 
> Same thing applies to function names to help you remember the type
> returned.
> 


And is absolutely horrible! It serves little purpose especially in the world of
C++ as we can invent our own data types and attempting to extend the convention
to include our newly defined types makes the code unreadable.

In addition it makes it difficult to change a int to an unsigned int or to 
a long without updating every occurence of the variable name in the code.


-- 
Keith Whittingham
wgk@zurich.ibm.com

Re: Hungarian notation

[Peter Seebach]

In article <3198F30F.2A2@zurich.ibm.com>,
Keith Whittingham  <wgk@zurich.ibm.com> wrote:
>Roger Merritt wrote:
>> The idea is that you include information in the name of the variable
>> to help you remember the type. So a pointer to a char might be named
>> cpCurrent.

>> Same thing applies to function names to help you remember the type
>> returned.

>And is absolutely horrible! It serves little purpose especially in the world
>of C++ as we can invent our own data types and attempting to extend the
>convention to include our newly defined types makes the code unreadable.

(Please note that this is in several groups other than clc++.)

Please don't blame Hungarian for that.  I lack the rigor and devotion
necessary to even design, let alone use, a Hungarian style naming
convention, but I feel compelled to defend it.

It has *nothing* to do with this idiotic practice of prefixing things with
their low-level types.  The intent was that *for any specific project* you
would devise a naming convention which tagged things with their high-level
type.  For instance, if you used size_t a lot, you might use the prefix s,
so you would have sFoo for a size_t named Foo.  You would *not not not*
encode this as ui or ul.

The original Hungarian notation person has apparently written diatribes about
M$'s systematic destruction and violation of the original idea; I'd love to
see copies of this, so I could just mail them to people who keep quoting
and using the utterly evil and destructive form.

>In addition it makes it difficult to change a int to an unsigned int or to 
>a long without updating every occurence of the variable name in the code.

Only when done by the terminally naive.  If you use prefixes relating to
abstract types, it can be a helpful notational cue, without the @#*@#
idiocies of...

Well, nevermind, I've ranted enough.

-s
-- 
Peter Seebach - seebs@solon.com - Copyright 1996 Peter Seebach.
Does anyone read these things?  I doubt it, but I've never been sure.
Unsolicited email is not welcome, and will be billed for at consulting rates.
The *other* C FAQ - http://www.solon.com/~seebs/c/c-iaq.html

Re: Hungarian notation

[Pete Becker]

In article <4na9r2$qin@solutions.solon.com>, seebs@solutions.solon.com says...
>
>In article <3198F30F.2A2@zurich.ibm.com>,
>Keith Whittingham  <wgk@zurich.ibm.com> wrote:
>>Roger Merritt wrote:
>>> The idea is that you include information in the name of the variable
>>> to help you remember the type. So a pointer to a char might be named
>>> cpCurrent.
>
>>> Same thing applies to function names to help you remember the type
>>> returned.
>
>>And is absolutely horrible! It serves little purpose especially in the world
>>of C++ as we can invent our own data types and attempting to extend the
>>convention to include our newly defined types makes the code unreadable.
>
>(Please note that this is in several groups other than clc++.)
>
>Please don't blame Hungarian for that.  I lack the rigor and devotion
>necessary to even design, let alone use, a Hungarian style naming
>convention, but I feel compelled to defend it.
>
>It has *nothing* to do with this idiotic practice of prefixing things with
>their low-level types.  The intent was that *for any specific project* you
>would devise a naming convention which tagged things with their high-level
>type.  For instance, if you used size_t a lot, you might use the prefix s,
>so you would have sFoo for a size_t named Foo.  You would *not not not*
>encode this as ui or ul.
>
>The original Hungarian notation person has apparently written diatribes about
>M$'s systematic destruction and violation of the original idea; I'd love to
>see copies of this, so I could just mail them to people who keep quoting
>and using the utterly evil and destructive form.

Nevertheless, when someone posts a message on this newsgroup asking about 
Hungarian notation they are almost certainly referring to the utterly evil and 
destructive form, and need to be set on the right track.

Re: Hungarian notation

[Mark Chu-Carroll]

In article <4ndb2j$1p0q@uni.library.ucla.edu>,
Jay Martin <jmartin@cs.ucla.edu> wrote:
>Even imporant projects at Microsoft do not use Hungarian notation:
>
>"Cutler (Mr VMS/NT) and his team reject Hungarian. This pleased Wood, who
>called Hungarian "the stupidest thing I'd ever seen." "
> 
>-- From NT project reflection book: Showstopper! by G Pascal Zachary, pg 56.
>
>Hungarian notation is just another idiotic established concepts
>thriving in the computer science field. Isn't CS wonderful?  I point
>my finger at the totally inattentive and spaced-out
>software-incompetent clowns in CS academia.

Before you get too smug in your anti-academic sneering, you might want
to consider the fact that hungarian notation is almost entirely an
*industrial* practice. In my experience, virtually all of those
academics that you're so busy sneering at think that hungarian naming
is an incredibly foolish idea.

The current vogue for hungarian naming was started by Microsoft, and
has propogated mainly through the use of Microsoft software
development products. Current academic thought on software development
and engineering tends to stress formal design, and a high level of
abstraction - which is directly counter to the currently popular
variant of hungarian naming.

	<MC>
-- 
Mark Craig Chu-Carroll          || "I'm not dumb, 
IBM T.J. Watson Research Center || I just have a command of thoroughly useless
mcc@watson.ibm.com              || information." --- Calvin

Re: Hungarian notation

[Jay Martin]

>Before you get too smug in your anti-academic sneering, you might want
>to consider the fact that hungarian notation is almost entirely an
>*industrial* practice. In my experience, virtually all of those
>academics that you're so busy sneering at think that hungarian naming
>is an incredibly foolish idea.

>The current vogue for hungarian naming was started by Microsoft, and
>has propogated mainly through the use of Microsoft software
>development products. Current academic thought on software development
>and engineering tends to stress formal design, and a high level of
>abstraction - which is directly counter to the currently popular
>variant of hungarian naming.

No what I am talking about is the incompetent job computer science
academia is doing researching and teaching software especially at the
top schools who have mostly declared the software subject as "unworthy
of study".  Subtract CMU and the there is maybe 5 profs in the top 15
CS depts that study software.  It is completely likely that a student
at the major schools to get a BS and then a PHD and be pretty much
incompetent in software.  This negatively effects the software
industry.

Lets see, Charles Simonyi (Mr Hungarian notation):
  PHD Computer Science Stanford (#1 CS).  (From MS secrets).

Heh, I rest my case (well unless he got his PHD in the 60's, but you
get the basic idea)

Jay

PS : What does Stanford teach as a first language?   A: C.
     Fun Quote from Stanford CS grad:" Hey, this compiler won't let
     me do a inter-procedural GOTO!!!!"
     Fun quote form Berkeley CS grad:"I do low level pointer arithmetic
     because the COMPILER may compile my code faster."

Re: Hungarian notation

[Scott]

jmartin@cs.ucla.edu (Jay Martin) wrote:
>
> No what I am talking about is the incompetent job computer science
> academia is doing researching and teaching software especially at the
> top schools who have mostly declared the software subject as "unworthy
> of study". 
I guess I'm confused.  What is it you think academia is teaching?
What are the options?  Only two I know are hardware or software.
Scott

Re: Hungarian notation

[G.O.Visser]

Ici je suis encore un fois

Re: Hungarian notation

[Steve Branam]

Jay Martin wrote:
> 
> Even imporant projects at Microsoft do not use Hungarian notation:
> 
> "Cutler (Mr VMS/NT) and his team reject Hungarian. This pleased Wood, who
> called Hungarian "the stupidest thing I'd ever seen." "
> 
> -- From NT project reflection book: Showstopper! by G Pascal Zachary, pg 56.
> 
> Hungarian notation is just another idiotic established concepts
> thriving in the computer science field. Isn't CS wonderful?  I point
> my finger at the totally inattentive and spaced-out
> software-incompetent clowns in CS academia.
> 
> Jay

A little history, the practice at Digital for code written in Macro and
BLISS (the primary languages for OS development in the old days) was
to use notation similar to Hungarian. All the primitive data types had
a code assigned to them (i.e. "l" for longword, "w" for word, "q" for
quadword, etc.). You can see this in the VMS system service programming
docs. This was especially useful in assembly language, when you had
to make sure you used the right mnemonics for the size operand you
were using (so you didn't do a "move word" on a longword-size field!).

I found this to be annoying in high-level languages, where I specifically
did *not* want to encode implementation details in names. Over the years
I have worked with various other people's code that used different 
styles of coded naming conventions. About the only one I ever found
useful was the use of "p" for pointer (which could be extended to "r"
for reference in C++) so I would remember that I had a pointer to a 
thing, not the thing itself. 
-- 
Steve Branam                Hub Products Engineering          508-486-6043
branam@dechub.lkg.dec.com   Digital Equipment Corporation     DTN 226-6043

Re: Hungarian notation

[Scott]

jmartin@cs.ucla.edu (Jay Martin) wrote:
>
> Even imporant projects at Microsoft do not use Hungarian notation:
> 
> "Cutler (Mr VMS/NT) and his team reject Hungarian. This pleased Wood, who
> called Hungarian "the stupidest thing I'd ever seen." "
>  
> -- From NT project reflection book: Showstopper! by G Pascal Zachary, pg 56.
> 
> Hungarian notation is just another idiotic established concepts
> thriving in the computer science field. Isn't CS wonderful?  I point
> my finger at the totally inattentive and spaced-out
> software-incompetent clowns in CS academia.
> 
> Jay
Such as Charles Petzold?

Scott

Re: Hungarian notation

[Giuliano Carlini]

In <4ne6o8$1m7g@sol.caps.maine.edu> Scott <slary61@maine.maine.edu>
writes: 
>
>jmartin@cs.ucla.edu (Jay Martin) wrote:
>> I point
>> my finger at the totally inattentive and spaced-out
>> software-incompetent clowns in CS academia.
>> 
>> Jay

I'm really surprised at the anti academic sentiment I often hear from
those working in the trenches around me. An academics job is to
discover new approaches and techniques. Sometimes they work and
sometimes they don't. But, you can't tell until you try them. And often
what you or I loathe is held dear by other "real" programmers.

The basis of almost every tool I use was created by an academic. Their
successes vastly outweigh their failures.

Lastly, I don't believe that we can lay the blame for Hungarian on
academics. I believe that it was a Microsoft employee who is
responsible for this abomination. But, I'm not sure.

g

Re: Hungarian notation

[Warren Young]

giuliano@ix.netcom.com(Giuliano Carlini) wrote:

>Lastly, I don't believe that we can lay the blame for Hungarian on
>academics. I believe that it was a Microsoft employee who is
>responsible for this abomination. But, I'm not sure.

Charles Simonyi does work for Microsoft (chief architect or some
such), and it was his influence there that led HN to appear in Charles
Petzold's highly-successful Programming Windows 3.1.  HN spread from
there, as far as I can tell; the primary reason I think it spread is
the Windows API's strong reliance on low-level data types, value
"packing" (putting two words in a long, for example) and such --
keeping track of this sort of thing is a real bear, without some
crutches.

I would like to point out that HN _first_ appeared in Simonyi's
doctoral thesis.  So, I guess you could say that it was an academic's
idea, originally.

I do want to renew my assertion that HN is born of generally good
thinking and good intentions, though, especially as originally
envisioned.  Neither "true HN" nor "Microsoft HN" are "right", IMHO,
but I've evolved a variant that I've found pretty helpful.  In fact,
it's really more of a formaized variable naming procedure than a
method of documenting the type of a variable.  One day I'll get around
to working up a semi-formal paper about it...

= Warren -- http://www.cyberport.com/~tangent

Re: Hungarian notation

[Matt Kennel]

Peter Seebach (seebs@solutions.solon.com) wrote:

: Only when done by the terminally naive.  If you use prefixes relating to
: abstract types, it can be a helpful notational cue, without the @#*@#
: idiocies of...

This is better than the dumb interpretation, but I don't feel it's
that important. 

The names of variables should not really be a major issue, however
the names in the interface of a *CLASS* are!  

Any 'major' piece of data will be in some interface anyway. 

This is where strict style conventions which relate concepts not
directly expressible in the language technology may be valuable.

: Peter Seebach - seebs@solon.com - Copyright 1996 Peter Seebach.

Re: Hungarian notation

[Dave Mikesell]

In article <3198F30F.2A2@zurich.ibm.com> Keith Whittingham <wgk@zurich.ibm.com> writes:

>Roger Merritt wrote:

>> The idea is that you include information in the name of the variable
>> to help you remember the type. So a pointer to a char might be named
>> cpCurrent.
>> 
>> Same thing applies to function names to help you remember the type
>> returned.
>> 


>And is absolutely horrible! It serves little purpose especially in the world of
>C++ as we can invent our own data types and attempting to extend the convention
>to include our newly defined types makes the code unreadable.

>In addition it makes it difficult to change a int to an unsigned int or to 
>a long without updating every occurence of the variable name in the code.

	I second that emotion...

Re: Hungarian notation

[Dr S.J. Harris]

In article <3198F30F.2A2@zurich.ibm.com> Keith Whittingham <wgk@zurich.ibm.com> writes:
>Roger Merritt wrote:
>> 
>> Franz.Kruse@erno.de (Franz Kruse) wrote:
>> 
>> >Could someone please post an article describing Hungarian Notation in some detail
>> >and giving examples?
>> 
>> >Thanks,
>> 
>> >Franz
>> 
>> The idea is that you include information in the name of the variable
>> to help you remember the type. So a pointer to a char might be named
>> cpCurrent.
>> 
>> Same thing applies to function names to help you remember the type
>> returned.
>> 
>
>
>And is absolutely horrible! It serves little purpose especially in the world of
>C++ as we can invent our own data types and attempting to extend the convention
>to include our newly defined types makes the code unreadable.
>
>In addition it makes it difficult to change a int to an unsigned int or to 
>a long without updating every occurence of the variable name in the code.
>
Isn't that supposed to be one of the 'good features' of Hungarian notation.
That it forces you to go through your code and check at each occurrance that
your change of type is not going to have any nasty effects. (Unless, you're
lazy and do a global search and replace ;^)

By the way, I hate Hungarian notation too. I like symbol names that I can
read out aloud if necessary.

>
>-- 
>Keith Whittingham
>wgk@zurich.ibm.com

Simon J Harris
(s.j.harris@ic.ac.uk)

Re: Hungarian notation

[Gerolf Wendland]

Dr S.J. Harris wrote:
> By the way, I hate Hungarian notation too. I like symbol names that I can
> read out aloud if necessary.

How right you are!

G.

Re: Hungarian notation

[mAg]

In article <31999F43.41C67EA6@scn.de> (Wed, 15 May 1996 11:09:23 +0200), 
wendland%hpp015%hpp001.mch2.scn.de@scn.de says :
>
>Dr S.J. Harris wrote:
>> By the way, I hate Hungarian notation too. I like symbol names that I 
can
>> read out aloud if necessary.
>
>How right you are!
>
>G.

Hungarian Notation is an excellent concept, but I am sure that it will be 
appreciated only by the programmers who have to work with serious code and 
maintain it for years. For others who write smaller programs, it may not 
even be necessary, because there is not need to convey the implementation 
specific stuff in the variable name, because they can shout and ask the 
other programmer in the next office...


-- 
/* --------------------------------------------------------
                      MAG@ESKIMO.COM
http://www.eskimo.com/~mag/index.html
***********************************************************
To understand recursion one must first understand recursion
***********************************************************
-------------------------------------------------------- */

Re: Hungarian notation

[Arne W Flones]

mAg wrote:
> 
> Hungarian Notation is an excellent concept, but I am sure that it will be
> appreciated only by the programmers who have to work with serious code and
> maintain it for years. [snip]

B.S!!  It is a b-a-a-a-a-a-d idea.  It is an idiotic coding standard.  In "Programming Pearls," 
Jon Bentley tells us to debug the code, not the comments.  With Microsoft's idea, we now must 
remember to debug the code, not the Hungarian Notation.  Hungarian notation is a horrible idea.  
These kinds of standards are an attempt to make code readable when there are multiple 
programmers.  Unfortunately, they never work.

Case in point:  The first time somebody wants to change the type of an identifier and doesn't 
want to grep through all the source code to find all uses of the variable, Hungarian Notation 
stops working.  As is ALWAYS the case, this will happen, especially in a large project.

Variable naming conventions always break down.  I don't use them.

Regards,
Arne
flonesaw@netonecom.net

Re: Hungarian notation

[Norman L. Reitzel]

In article <319D2278.3F9A@netonecom.net> Arne W Flones <flonesaw@netonecom.net> writes:
>mAg wrote:
>> 
>> Hungarian Notation is an excellent concept, but I am sure that it will be
>> appreciated only by the programmers who have to work with serious code and
>> maintain it for years. [snip]
>
>B.S!!  It is a b-a-a-a-a-a-d idea.  It is an idiotic coding standard.  In "Programming Pearls," 
>Jon Bentley tells us to debug the code, not the comments.  With Microsoft's idea, we now must 
>remember to debug the code, not the Hungarian Notation.  Hungarian notation is a horrible idea.  
>These kinds of standards are an attempt to make code readable when there are multiple 
>programmers.  Unfortunately, they never work.
>
>Case in point:  The first time somebody wants to change the type of an identifier and doesn't 
>want to grep through all the source code to find all uses of the variable, Hungarian Notation 
>stops working.  As is ALWAYS the case, this will happen, especially in a large project.
>
What's worse, Arne, somebody will change the type, say from szShortSTring 
to pszReallyLongString, find that it's referenced a zillion times, and 
"fix" it by changing the name BACK, and then changing some (but not all) 
of the context of the reference.  If we're lucky, the stuff left out is 
in a really well used chunk of code and breaks things immediately.  If 
not, we've turned a good piece of software into a crash waiting to happen.

Worse worse, the "p" thing.  I -HATE- (stronger word?) "p" variables.  I 
want to see every last dereference, not have them take place by default.  
I attribute about half of the reason Pascal programmers don't much use 
pointers to the fool notion that a "pointer to something" is not an 
abstract object in it's own right, and merely represents an alternate 
name for the original object.  I cannot conceive of a more error-prone 
concept than an "alternate name".

As for serious code, I've ported million line projects for a telephone 
company, and managed projects that produced twice that.  The key to 
maintainability is defensive programming, and ADEQUATE BLOCK COMMENTS.  
Any chunk of code that does not contain info about what it does and how 
it does it is an error waiting to happen.  The rude concept of 
"self-documenting" code belongs in an ivory tower with those who teach, 
not in the trenches with those of us who DO.



-- 
   Norman L. Reitzel, Jr.       |    "When you live beside the graveyard,
   nreitzel@lonestar.utsa.edu   |     you can't cry for every funeral."
   Blue Water Ventures, dba.    |                     Russian Proverb

Re: Hungarian notation

[Richard A. O'Keefe]

nreitzel@lonestar.jpl.utsa.edu (Norman L. Reitzel   ) writes:
>As for serious code, I've ported million line projects for a telephone 
>company, and managed projects that produced twice that.  The key to 
>maintainability is defensive programming, and ADEQUATE BLOCK COMMENTS.  
>Any chunk of code that does not contain info about what it does and how 
>it does it is an error waiting to happen.  The rude concept of 
>"self-documenting" code belongs in an ivory tower with those who teach, 
>not in the trenches with those of us who DO.

Those of us who teach struggle hard to persuade students to write
good comments.  Hereabouts, we're even _marking the comments_ as
well as the code, much to the annoyance of students who say "why
did I get only 50% when my code works?"  So far this semester I
reckon I've spent nearly 10 hours preaching on the need for good
comments, and what that means.  Things like remembering that your
main task in writing a module is to explain to the next programmer
everything s/he needs to understand why your module works (or in
reality, why it doesn't).

I believe I have actually succeeded in teaching this to one student,
by giving her a 16 000 line C program to maintain, and pointing out
as she struggled "you are trying to debug this, are you?  Well, I
can't help because I don't know what the major data structure of
this module looks like; the original programmer knew, but HE DIDN'T
TELL YOU.  That was mean of him, wasn't it?  You don't want people
to dislike you the way you are starting to dislike him, do you?"

If there is any easier way to get the message across, I'd like to
hear about it.

Remember, us ivory tower types have to read a _ton_ of very badly
written code in order to mark it.  Here at RMIT anyway, we care a
lot about trying to teach good practice, because every good point
we get across makes marking that much less painful for ourselves.

-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

Re: Hungarian notation

[Peter Moylan]

Richard A. O'Keefe (ok@goanna.cs.rmit.EDU.AU) wrote:
>nreitzel@lonestar.jpl.utsa.edu (Norman L. Reitzel   ) writes:
>>As for serious code, I've ported million line projects for a telephone 
>>company, and managed projects that produced twice that.  The key to 
>>maintainability is defensive programming, and ADEQUATE BLOCK COMMENTS.  
>>Any chunk of code that does not contain info about what it does and how 
>>it does it is an error waiting to happen.  The rude concept of 
>>"self-documenting" code belongs in an ivory tower with those who teach, 
>>not in the trenches with those of us who DO.

>Those of us who teach struggle hard to persuade students to write
>good comments.

I don't know where this myth comes from.  In my 20+ years in
academia, I have NEVER met a software teacher who considered
uncommented code to be acceptable.  Practically everyone tries
to get across the message "write the comments first, and then
the code".

Take a look at some of the literature on "literate programming".
I'm not convinced myself that that's the solution, but at
least it does illustrate the attitude, which is very common
in academia, that the comments are more important than the code.

It's true, however, that it's very difficult to get students
to listen to this message.  The value of comments seems to be
a "hindsight" thing that one learns only by first making some
bad mistakes.

I adopted a policy, years ago, of never agreeing to help
debug badly-documented code.  When I'm asked questions like
"why doesn't my code work", my response is along the lines
of "come back after you've inserted the comments, and we'll
look at it then".  Half the time they don't come back, 
because they discover the error themselves while debugging
the comments.

One of the subjects I teach involves a large team
programming job.  Typically the work progresses very badly
for the first few months, but by the end of it the students
have learnt something about the importance of good
communication among team members.  I don't particularly
care whether the final product is a good one - usually it
isn't - provided that the students have properly learnt the
lessons about how to do it better next time.  The major
value of this subject, in my opinion, is that it teaches
students by experience that a large software project is
radically different from "hello world" programming.

>Fifty years of programming language research, and we end up with C++ ???

A long-standing debate in academic teaching circles is over
the question of whether one should teach a good programming
language, or teach the one that's most commonly used.
Years ago this debate was about COBOL, and in the end most
CS departments stuck to their guns and dropped COBOL, over
the protests of most employers, on the grounds that it was
simply perpetuating bad practice.  Now COBOL is almost a
non-issue and the focus of the debate has moved to C and C++;
but this time around the CS departments - most of them,
anyway - have opted for the morally lazy solution.  Everyone
seems to have forgotten the message that universities are
supposed to be looking to the future rather than simply
trailing the pack.

Some of my colleagues in another department are still using
Fortran as their teaching language, based on an "industry
practice" argument.  Apparently they haven't yet noticed
that industry practice is moving on and leaving them behind.

--
Peter Moylan                           peter@ee.newcastle.edu.au
                  http://www.eng.newcastle.edu.au/ee/Moylan.html
OS/2 freeware list at 
      http://www.eng.newcastle.edu.au/ee/Moylan/os2/os2info.html

Re: Hungarian notation

[Andy Ho-Fan Chan]

In article <4o07o9$rfu@seagoon.newcastle.edu.au>, peter@tesla.newcastle.edu.au wrote:

>I adopted a policy, years ago, of never agreeing to help
>debug badly-documented code.  When I'm asked questions like
>"why doesn't my code work", my response is along the lines
>of "come back after you've inserted the comments, and we'll
>look at it then".  Half the time they don't come back, 
>because they discover the error themselves while debugging
>the comments.

Well, I guess they just don't want to comment the code and don't come to ask 
you question anymore.  I'm a student in CS, and I know what the students feel. 
 When the project is dued soon and don't get the program works, do you still 
have time to comment to code?

Well, comment is important, but in academic, most of the time no one wants to 
do that.

>A long-standing debate in academic teaching circles is over
>the question of whether one should teach a good programming
>language, or teach the one that's most commonly used.
>Years ago this debate was about COBOL, and in the end most
>CS departments stuck to their guns and dropped COBOL, over
>the protests of most employers, on the grounds that it was
>simply perpetuating bad practice.  Now COBOL is almost a
>non-issue and the focus of the debate has moved to C and C++;
>but this time around the CS departments - most of them,
>anyway - have opted for the morally lazy solution.  Everyone
>seems to have forgotten the message that universities are
>supposed to be looking to the future rather than simply
>trailing the pack.

It's true, but a lot of college are still stuck with Pascal, or Modula.

>Some of my colleagues in another department are still using
>Fortran as their teaching language, based on an "industry
>practice" argument.  Apparently they haven't yet noticed
>that industry practice is moving on and leaving them behind.

Well, there are a lot of "language die-hard" programmers.  We can't do 
anything to them to swtich anyway.


======================== Andy Ho-Fan Chan =========================

 Tel. : (714)852-1000 x 484    Procom Technology, Inc.            
 email: andyc@procom.com       Software Engineering Department    
                               2181 Dupont Drive, Irvine, CA 92715

============ http://www.procom.com:80/~andyc/index.htm ============

Re: Hungarian notation

[Robert Dewar]

IWell, I guess they just don't want to comment the code and don't come to ask
you question anymore.  I'm a student in CS, and I know what the students feel.
 When the project is dued soon and don't get the program works, do you still
have time to comment to code?"

On the contrary, my students know that working code is useless to hand in
if it is not commented, so they *have* to comment the code. In fact a
well-commented and well-designed but not quite working assignment gets
much more credit than a fully working program which is poorly designed,
or has incomplete or incomprehensible comments. 

In the case of Ada package specs, comments *are* part of the spec, they
are as important as the code itself. It is remarkable how students react
if they know that this is the ground rule. All my students this semester
did a good job of commenting code!

Re: Hungarian notation

[Bob Rodgers]

dewar@cs.nyu.edu (Robert Dewar) wrote:
>Well, I guess they just don't want to comment the code and don't come to ask
>you question anymore.  I'm a student in CS, and I know what the students feel.
> When the project is dued soon and don't get the program works, do you still
>have time to comment to code?"

Yes.  Yes, you certainly do.  In fact, if you haven't been commenting
all along, that's probably why you're pushing the deadline and the
project doesn't work yet.

The time to start programming right is *now*, not later.  I laugh when
I see or hear a CS teacher who says they get caught by the assignment
= in conditional expressions, since no modern compiler lacks the
ability to flag this as an error (or the old constant-first trick,
e.g., "if(3 = x)" will **always** error)  if you decide to read one or
two pages of documentation.

>On the contrary, my students know that working code is useless to hand in
>if it is not commented, so they *have* to comment the code. In fact a
>well-commented and well-designed but not quite working assignment gets
>much more credit than a fully working program which is poorly designed,
>or has incomplete or incomprehensible comments. 

One of the problems in CS is the focus on "execution" correctness
instead of overall correctness.  It's a lot easier to grade (it either
works, or it doesn't), but it doesn't really address student
difficulties (especially with pointers, which kill first year student
projects all the time without them even knowing how to identify it as
anything but "it's acting weird, time to reboot"), nor grade on the
quality of the code.

One thing I remember, and will always remember, is a statement from a
teacher: "If you have a bug, you have an error."  I was quite frankly
surprised at how many students didn't realize this -- instead, they
tried to solve project problems with various degrees of mojo --
rebooting, renaming their data files, changing where things are in a
file, compiling with and without debug code.  Some beleagered students
will actually print out their project and re-type the "problem
sections" -- accidently fixing errors, or making them less apparent
(i.e., serious pointer problems that, by happenstance, make the
program crash sooner or later, or not at all, even though they haven't
actually moved).

CS education is in a sorry state when the only criteria to pass a
class are the ability to memorize the string function examples and get
a project working, even if it's spaghetti.

Re: Hungarian notation

[Robert A Duff]

In article <dewar.832897378@schonberg>, Robert Dewar <dewar@cs.nyu.edu> wrote:
>IWell, I guess they just don't want to comment the code and don't come to ask
>you question anymore.  I'm a student in CS, and I know what the students feel.
> When the project is dued soon and don't get the program works, do you still
>have time to comment to code?"
>
>On the contrary, my students know that working code is useless to hand in
>if it is not commented, so they *have* to comment the code. In fact a
>well-commented and well-designed but not quite working assignment gets
>much more credit than a fully working program which is poorly designed,
>or has incomplete or incomprehensible comments. 

Well, I'm not an ivory-tower academic like Robert is (*), but I very
much agree with this strategy.  The thing people have to learn is that
comments actually help you get the code to work right.  Comments are not
just a chore that silly professors require.  Somebody who says, "I don't
have time to write all those comments" is missing the point.

>In the case of Ada package specs, comments *are* part of the spec, they
>are as important as the code itself. It is remarkable how students react
>if they know that this is the ground rule. All my students this semester
>did a good job of commenting code!

Well, that's not too surprising, but it doesn't prove anything.  My
first-grade teacher required that I put my name on the upper-left-hand
corner of the page.  I didn't learn that "In civilized society, it's
right to put one's name on the upper-left-hand corner of the page."  I
learned, "To satisfy this teacher, I need to put my name on the
upper-left-hand corner of the page."  And I did it.  But my second-grade
teacher demanded that I put my name on the upper-RIGHT-hand corner.  How
do you convince students that comments are actually *useful*, and
actually make it *easier* to write programs?  It's hard, since it's not
true for small programs.

I once read an article by some professor who had written a program that
judged the "style" of programs submitted for assignments.  He judged
this program a success, because after some time, students' programs did
in fact get better style ratings, according to this style-judging
program.  Circular reasoning.  (The program counted the number of lines
of comments per line of code, the average length of identifiers, and so
forth.)

- Bob

P.S. (*) I hope Robert realizes I'm kidding about "ivory-tower
academics".  ;-)  He has, in fact, participated in professional
programming projects.

P.P.S. My take on comments is: Comment (only) where necessary.  Whenever
you can express some fact in the programming language, it's better to do
that than to write a comment.  Any time you feel the need to write a
comment, that's a failure of the programming language -- it can't
express what you need to say.  Note that lower-level languages need more
comments than higher-level languages.  But we're very far from having
programming languages that can express everything that needs to be said.
So we badly need comments.

Re: Hungarian notation

[Richard A. O'Keefe]

bobduff@world.std.com (Robert A Duff) writes:

>P.P.S. My take on comments is: Comment (only) where necessary.  Whenever
>you can express some fact in the programming language, it's better to do
>that than to write a comment.

I like reducing things to slogans.
I haven't been able to come up with a good one for this.
What I say is
	"Your comments should tell a human reader precisely the
	 things s/he needs to understand the purpose and operation
	 of the module but are not obvious from the code."
This is the right stuff, but it needs to be said better.
Can anyone come up with a really memorable way of expressing this?

>Any time you feel the need to write a
>comment, that's a failure of the programming language -- it can't
>express what you need to say.

I don't know that I agree with this.  How can the code make it clear
why you chose *not* to do something?  How does the code describe
the space of possible tradeoffs from which you selected this particular
point and why?

-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

Re: Hungarian notation

[Janus]

ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe) wrote:
>I like reducing things to slogans.
>I haven't been able to come up with a good one for this.
>What I say is
>	"Your comments should tell a human reader precisely the
>	 things s/he needs to understand the purpose and operation
>	 of the module but are not obvious from the code."
>This is the right stuff, but it needs to be said better.
>Can anyone come up with a really memorable way of expressing this?

"I understand c, I don't understand your program, explain it."



Bye from
Janus at Kerry, Ireland
email : jab@iol.ie
WWW : http://www.iol.ie/~jab

Re: Hungarian notation

[Jeff Dege]

On 28 May 1996 19:41:13 +1000, Richard A. O'Keefe (ok@goanna.cs.rmit.EDU.AU) wrote:
: bobduff@world.std.com (Robert A Duff) writes:
: 
: >Any time you feel the need to write a
: >comment, that's a failure of the programming language -- it can't
: >express what you need to say.
: 
: I don't know that I agree with this.  How can the code make it clear
: why you chose *not* to do something?  How does the code describe
: the space of possible tradeoffs from which you selected this particular
: point and why?

    I find that the more closely I can map the language to the problem,
the fewer comments I need.  My C++ code is much more sparsely commented
than my C code ever was, and I know I'm not the only programmer for whom
that is true.  I am strongly of the opinion that the best place to 
document a system is in the code.  But do I think that a programming
language will ever evolve to the point where no comments are necessary?
No, I can't say that I do.

-- 
When cryptography is outlawed, bayl bhgynjf jvyy unir cevinpl.

Re: Hungarian notation

[Michael Furman]

In article <4oehnp$onn@goanna.cs.rmit.EDU.AU>, 
ok@goanna.cs.rmit.EDU.AU 
says...
>
>I like reducing things to slogans.
>I haven't been able to come up with a good one for this.
>What I say is
>        "Your comments should tell a human reader precisely the
>         things s/he needs to understand the purpose and 
operation
>         of the module but are not obvious from the code."
>This is the right stuff, but it needs to be said better.
>Can anyone come up with a really memorable way of expressing 
this?
>

I am afraid it is impossible because your rule is a quite 
ambigious. I
generally agree with it, but every time we need to define what 
"obvious" 
mean. For
which kind of person? (what level of knowledge of programming, 
this
particular language, problem domain, math (if related), design of 
this
software ...)? And for what level of anderstanding (what is it, 
how to use
this module, how it works, some kind of proof of its correctness).
I just want to say, that IMO it is not so easy. I tried to define
such rule many times but never was satisfied.

---------------------------------------------------------------
Michael Furman,                       (603)893-1109
Geophysical Survey Systems, Inc.  fax:(603)889-3984
13 Klein Drive - P.O. Box 97          engr@gssi.mv.com 
North Salem, NH 03073-0097            71543.1334@compuserve.com
---------------------------------------------------------------

Re: Hungarian notation

[Richard A. O'Keefe]

ENGR@GSSI.MV.COM (Michael Furman) writes:
>I am afraid it is impossible because your rule is a quite 
>ambiguous. I generally agree with it, but every time we need to define what 
>"obvious" mean. For which kind of person?

I wouldn't say "ambiguous".  I prefer "gnomic", and will accept "vague".

The comments I put in code intended to be read by 2nd year students
are far more detailed and assume far less than comments I put in code
intended to be read by 4th year students.

This is actually part of the problem.  Students are exposed to a *lot*
of "textbook" code, whose authors have put in comments *to explain the
LANGUAGE* as well as a the code.  Things that a programmer who already
knows the language would call "junk comments" are put in to help students
who _don't_ know the language well, and students learn to imitate that.

I recently bought "The Microsoft(R) Manual of Style for Technical
Publications".  There is some very good stuff in there.  It introduced
me to a term I didn't know: "callout" (basically, you have a diagram
and a legend and a line that connects the legend to the place in the
diagram it comments on).

This suggests to me that a better way to annotate code for inclusion
in textbooks is

	- embedded in the code, place the comments you would normally
	  use for a programmer who understands the language but not
	  this particular program

	- either number the lines, and key language-oriented annotations
	  to the line numbers, perhaps putting code on the left page and
	  annotations on the facing right page

	- or use callouts for language-oriented annotations.

What's a better way?
-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

Commenting (was Re: Hungarian notation)

[Alan Bowler]

In article <4omejm$j3a@goanna.cs.rmit.EDU.AU> ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe) writes:
>
>This is actually part of the problem.  Students are exposed to a *lot*
>of "textbook" code, whose authors have put in comments *to explain the
>LANGUAGE* as well as a the code.  Things that a programmer who already
>knows the language would call "junk comments" are put in to help students
>who _don't_ know the language well, and students learn to imitate that.

I don't think that it is the textbooks particularly.  People add
comments to document the stuff that is not immediately obvious
to them.  Beginning programmers or people new to a language thus
often end up reminding themselves what the language construct does,
and we end up with the classic
     lda   3,dl          Put 3 into lower Q register

"classic" because the programmer later changed to the A register
but did not update the comment.

A more expirenced programmer would be familiar wth the machine
and would likely have commented on the logical effect of the
statement.  E.g.
      lda   3,dl        We need to loop three times.

Re: Commenting (was Re: Hungarian notation)

[Robert Dewar]

Richard said

"A more expirenced programmer would be familiar wth the machine
and would likely have commented on the logical effect of the
statement.  E.g.
      lda   3,dl        We need to loop three times.""

I don't like that as an example of experienced code, and in fact would
regard it as poor from a beginning student.

There is no point in repeating the 3, I can read a number. So the comment
would better read something like "setup to loop through sensor inputs"

And there is almost NEVER an excuse for a constant like 3 appearing 
directly in the code. Much better would be to declare a constant

number_of_sensors equ 3

and then write

     lda number_of_sensors, dl

in which case, the comment might well not be deemed so necessary.

Re: Commenting (was Re: Hungarian notation)

[Ken Garlington]

Robert Dewar wrote:
>       lda   3,dl        We need to loop three times.""
> 
> I don't like that as an example of experienced code, and in fact would
> regard it as poor from a beginning student.

I occasionally had such comments in my code, when I was learning assembly.
Of course, this was because the student assember required that 75% of the
code lines have trailing comments before it would do the assembly! :)

Re: Hungarian notation

[Steve Willer]

ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe) wrote:

>I recently bought "The Microsoft(R) Manual of Style for Technical
>Publications".  There is some very good stuff in there.  It introduced
>me to a term I didn't know: "callout" (basically, you have a diagram
>and a legend and a line that connects the legend to the place in the
>diagram it comments on).

This sounds interesting, but I don't really understand what you mean
here. Could you give an example of this?

Re: Hungarian notation

[Warren Young]

willer@carolian.com (Steve Willer) wrote:

>ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe) wrote:
>
>>me to a term I didn't know: "callout" (basically, you have a diagram
>>and a legend and a line that connects the legend to the place in the
>>diagram it comments on).
>
>This sounds interesting, but I don't really understand what you mean
>here. Could you give an example of this?

You see them all the time.  They come in several flavors, but they
basically all have a line pointing to something, and then a more
detailed description or whatever at the end of the line.  You see it
in drawing labels, "detail views", and drawing comments.  If you've
read Design Patterns, you have seen a form of callouts in its
pseudocode notation.

Naturally, this is all very graphical in nature, and just about
impossible to reproduce in a textual medium.  So, if you're writing a
book, you might have time to do this sort of thing, but if you're
hacking out some example code for your students, you probably don't.
So, I proposed using special comments to visually differentiate
explanatory comments from normal comments.  You might do something
like this:

	// Do [something] with the devices
	//! Note that the for loop runs from 0 to one less than the
	//! number of devices available.
	for (x = 0; x < kNumDevices; x++) {
		...

Notice the //! notation for introducing explanatory comments.  It's
easier than callouts, though it isn't as pretty.

= Warren -- http://www.cyberport.com/~tangent

Re: Hungarian notation

[Warren Young]

ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe) wrote:

>I recently bought "The Microsoft(R) Manual of Style for Technical
>Publications".  There is some very good stuff in there.  It introduced
>me to a term I didn't know: "callout" (basically, you have a diagram
>and a legend and a line that connects the legend to the place in the
>diagram it comments on).
...
>What's a better way?

Well, callouts do require more work.  You could get the same effect a
bit cheaper by adopting a commenting style that visually separates the
two types of comments.  Ideally, you should just be able to strip out
the "intro student" comments and still have a good program.

= Warren -- http://www.cyberport.com/~tangent

Re: Hungarian notation

[Chris Kuan]

Richard A. O'Keefe wrote:
> What I say is
>         "Your comments should tell a human reader precisely the
>          things s/he needs to understand the purpose and operation
>          of the module but are not obvious from the code."
> This is the right stuff, but it needs to be said better.
> Can anyone come up with a really memorable way of expressing this?
> 

What about something like, 

"Use comments to fill in the gaps between the code".

Of course, now you'll have to explain exactly what you intend by this,
but at least it's short and memorable, even if it doesn't appear
to make much sense at face value :-)

- Chris.

Re: Hungarian notation

[Bob Rodgers]

Chris Kuan <kuan.chris.ch@bhp.com.au> wrote:
>What about something like, 

>"Use comments to fill in the gaps between the code".

I read this and I get visions of hordes of students carefully
eliminating as much whitespace between and withing functions as
possible.


- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
------ http://www.wam.umd.edu/~rsrodger    rsrodger@wam.umd.edu -------

Re: Hungarian notation

[Chris Kuan]

Bob Rodgers wrote:
> 
> Chris Kuan <kuan.chris.ch@bhp.com.au> wrote:
> >What about something like,
> 
> >"Use comments to fill in the gaps between the code".
> 
> I read this and I get visions of hordes of students carefully
> eliminating as much whitespace between and withing functions as
> possible.

It just goes to show, some people will do ANYTHING rather
than comment their code reasonably :-)

- Chris.

Re: Hungarian notation

[Will Rose]

Richard A. O'Keefe (ok@goanna.cs.rmit.EDU.AU) wrote:
: bobduff@world.std.com (Robert A Duff) writes:

: >P.P.S. My take on comments is: Comment (only) where necessary.  Whenever
: >you can express some fact in the programming language, it's better to do
: >that than to write a comment.

: I like reducing things to slogans.
: I haven't been able to come up with a good one for this.
: What I say is
: 	"Your comments should tell a human reader precisely the
: 	 things s/he needs to understand the purpose and operation
: 	 of the module but are not obvious from the code."
: This is the right stuff, but it needs to be said better.
: Can anyone come up with a really memorable way of expressing this?

"Comment at one level above the code" - trouble is, this is a bit
cryptic and needs a comment to explain it...

: >Any time you feel the need to write a
: >comment, that's a failure of the programming language -- it can't
: >express what you need to say.

: I don't know that I agree with this.  How can the code make it clear
: why you chose *not* to do something?  How does the code describe
: the space of possible tradeoffs from which you selected this particular
: point and why?

I strongly disagree with the 'failure of the language' argument; I tend
to write comments at an intermediate level between the code and the
reader.  Obviously the code is written as clearly as possible, since
I have to debug it, but above that level it's handy to have reminders
of just what in the world is going on in a broader sense, and why.

The next level above comments is probably the manual, but that seldom
gets written.

Will
cwr@crash.cts.com

Re: Hungarian notation

[Ralph Silverman]

Will Rose (cwr@cts.com) wrote:
: Richard A. O'Keefe (ok@goanna.cs.rmit.EDU.AU) wrote:
: : bobduff@world.std.com (Robert A Duff) writes:

: : >P.P.S. My take on comments is: Comment (only) where necessary.  Whenever
: : >you can express some fact in the programming language, it's better to do
: : >that than to write a comment.

: : I like reducing things to slogans.
: : I haven't been able to come up with a good one for this.
: : What I say is
: : 	"Your comments should tell a human reader precisely the
: : 	 things s/he needs to understand the purpose and operation
: : 	 of the module but are not obvious from the code."
: : This is the right stuff, but it needs to be said better.
: : Can anyone come up with a really memorable way of expressing this?

: "Comment at one level above the code" - trouble is, this is a bit
: cryptic and needs a comment to explain it...

: : >Any time you feel the need to write a
: : >comment, that's a failure of the programming language -- it can't
: : >express what you need to say.

: : I don't know that I agree with this.  How can the code make it clear
: : why you chose *not* to do something?  How does the code describe
: : the space of possible tradeoffs from which you selected this particular
: : point and why?

: I strongly disagree with the 'failure of the language' argument; I tend
: to write comments at an intermediate level between the code and the
: reader.  Obviously the code is written as clearly as possible, since
: I have to debug it, but above that level it's handy to have reminders
: of just what in the world is going on in a broader sense, and why.

: The next level above comments is probably the manual, but that seldom
: gets written.

: Will
: cwr@crash.cts.com


--
************begin r.s. response***************

	let us go back to the beginning...
	why are there
		high level programming languages
	?
	because
		humans do not think in binary code
	as do computers!
	therefore a
		tension sill is found
	in such languages,  in that these must
		mediate
	this disparity.
	if too great a demand is placed on a
		programming language
	regarding 'human friendly'
	might this not result in limitation of the
	usefulness of the language for programming?
	particularly where skilled programmers
	are involved?

************end r.s. response*****************
Ralph Silverman
z007400b@bcfreenet.seflin.lib.fl.us

Re: Hungarian notation

[Michael Furman]

In article <4p4319$e10@nntp.seflin.lib.fl.us>, 
z007400b@bcfreenet.seflin.lib.fl.us says...
> [.....]
>        let us go back to the beginning...
>        why are there
>                high level programming languages
>        ?
>        because
>                humans do not think in binary code
>        as do computers!

Are you really believe that computers "think in binary code"?

---------------------------------------------------------------
Michael Furman,                       (603)893-1109
Geophysical Survey Systems, Inc.  fax:(603)889-3984
13 Klein Drive - P.O. Box 97          engr@gssi.mv.com 
North Salem, NH 03073-0097            71543.1334@compuserve.com
---------------------------------------------------------------

Re: Hungarian notation

[Heinz Hemken]

The point of comments in non-trivial software, and in programs that will
be read by many people, is not just to express what isn't clear in the
code itself.

Commercial or in-house software are assets, economically important
assets that no organization can afford to sacrifice or have fail. In
this context, comments should make it exquisitely clear what is going on
at a level understandable by just about anyone who will conceivably be
expected to help evolve or maintain the code.

Sparse comments due to "it's in the code", or because "the language
itself expresses what you need to say" will backfire with certainty one
day. It isn't poetry or literature, though it may often seem so, nor is
it an academic exercise, though many seem to think so. It is something
that MUST function and evolve correctly. In that light, it's probably
better to err in the direction of more comments rather than less.

-- 
Heinz Hemken
http://www.cell.cinvestav.mx/hh/bchh.html

Re: Hungarian notation

[Matt Kennel]

If you want an aphorism, what about this:

        Code the comments, don't comment code.

Re: Hungarian notation

[Jeff Dege]

On Sat, 01 Jun 1996 18:28:10 -0700, Heinz Hemken (hhemken@cell.cinvestav.mx) wrote:
: 
: Sparse comments due to "it's in the code", or because "the language
: itself expresses what you need to say" will backfire with certainty one
: day. It isn't poetry or literature, though it may often seem so, nor is
: it an academic exercise, though many seem to think so. It is something
: that MUST function and evolve correctly. In that light, it's probably
: better to err in the direction of more comments rather than less.

One of the fundamental principles of building non-fragile software
(i.e., software that doesn't break in maintenance) is to _never_
allow redundant information.  If a system depends upon two or more
pieces of information being in synch in order to work, it is broken,
or it will be after a couple of maintenance cycles.

Duplicating in the comments information that is clear from the code
opens the possibility that the comments will differ from the code,
which will result in programmers coding as if the comments are correct.

So I err in the direction of commenting what isn't in the code.  I.e.,
what something is supposed to do, why I did I do this, why didn't I
do that, what unexpected interactions might arise.  And, of course,
a continous log of changes and reasons for them.

-- 
You'd think that after all this time
I would have dreamed up a really clever .sig!

Re: Hungarian notation

[Ralph Silverman]

Heinz Hemken (hhemken@cell.cinvestav.mx) wrote:
: The point of comments in non-trivial software, and in programs that will
: be read by many people, is not just to express what isn't clear in the
: code itself.

: Commercial or in-house software are assets, economically important
: assets that no organization can afford to sacrifice or have fail. In
: this context, comments should make it exquisitely clear what is going on
: at a level understandable by just about anyone who will conceivably be
: expected to help evolve or maintain the code.

: Sparse comments due to "it's in the code", or because "the language
: itself expresses what you need to say" will backfire with certainty one
: day. It isn't poetry or literature, though it may often seem so, nor is
: it an academic exercise, though many seem to think so. It is something
: that MUST function and evolve correctly. In that light, it's probably
: better to err in the direction of more comments rather than less.

: -- 
: Heinz Hemken
: http://www.cell.cinvestav.mx/hh/bchh.html

--
************begin r.s. response*************

	comments are ignored,  generally,
		entirely
	by the
		system
	so these may be
		inaccurate,
		obsolete,
	or
		utterly ignorant and misleading!

	therefore
	an extremely defensive viewpoint is needed
	in dealing with these!
	as a result...
	these may reasonably be viewed as a kind of
		potentially valuable clutter!
	while a few good comments may be of great value...
	a large number of these are likely to be
		more trouble
	than
		they are worth!

	as a suggestion...
	until an automated means of generating
	and/or validating these is found...
	brevity should remain the soul of wit!

************end r.s. response***************
Ralph Silverman
z007400b@bcfreenet.seflin.lib.fl.us

Re: Hungarian notation

[Jeff Dege]

On 5 Jun 1996 13:28:40 GMT, Ralph Silverman (z007400b@bcfreenet.seflin.lib.fl.us) wrote:
: [ a lot of stuff that r.s. should have deleted, deleted ]
: ************begin r.s. response*************
: [ pointless meanderings deleted ]
: 
: 	as a suggestion...
: 	until an automated means of generating
: 	and/or validating these is found...
: 	brevity should remain the soul of wit!
: 
: ************end r.s. response***************

    It would have been a good idea.

-- 
    "[I]n fact, I didn't know that cats _could_ grin."
    "They all can," said the Duchess; "and most of 'em do."
    "I don't know of any that do," Alice said very politely, feeling quite
pleased to have gotten into a conversation.
    "You don't know much," said the Duchess; "and that's a fact."

Re: Hungarian notation

[Peter Moylan]

Andy Ho-Fan Chan (andyc@procom.com) wrote:
>In article <4o07o9$rfu@seagoon.newcastle.edu.au>, peter@tesla.newcastle.edu.au wrote:

>>I adopted a policy, years ago, of never agreeing to help
>>debug badly-documented code.  When I'm asked questions like
>>"why doesn't my code work", my response is along the lines
>>of "come back after you've inserted the comments, and we'll
>>look at it then".  Half the time they don't come back, 
>>because they discover the error themselves while debugging
>>the comments.

>Well, I guess they just don't want to comment the code and don't come to ask 
>you question anymore.  I'm a student in CS, and I know what the students feel. 
> When the project is dued soon and don't get the program works, do you still 
>have time to comment to code?

No argument with this ... we all know that that's what the
students feel.  Almost invariably, the reason given for
leaving out comments is "I don't have the time".

The real question, however, is this: if you have to get something
working quickly, do you still have time to NOT comment the code?

Or, to put it another way: would you rather spend half an
hour getting the comments right, or several days fighting
with the debugger?

This commenting business is not just an optional extra
to make your code look pretty.  The main reason for doing
a good job on the commenting is that it helps you code
a lot _faster_.

But <sigh!> many students - particularly the weaker students
- never seem to learn this point.  Show them the easy way
to get the job done, and they'll still stick stubbornly
to the hard way.

--
Peter Moylan                           peter@ee.newcastle.edu.au
                  http://www.eng.newcastle.edu.au/ee/Moylan.html
OS/2 freeware list at 
      http://www.eng.newcastle.edu.au/ee/Moylan/os2/os2info.html

Re: Hungarian notation

[Jeff Dege]

On 27 May 1996 00:44:35 GMT, Peter Moylan (peter@fourier.newcastle.edu.au) wrote:
: This commenting business is not just an optional extra
: to make your code look pretty.  The main reason for doing
: a good job on the commenting is that it helps you code
: a lot _faster_.
: 
: But <sigh!> many students - particularly the weaker students
: - never seem to learn this point.  Show them the easy way
: to get the job done, and they'll still stick stubbornly
: to the hard way.

How many teachers _teach_ this?  I've been through a BS program in CS, and
I'm half-way through an MS program in SE, and I've yet to have a class that
discussed issues of this sort.  The only place on campus where these issues
were discussed was in the office of the student chapter of the ACM.  (This
was the site of many an informative bull session between undergrads, grads,
and the occasional faculty advisor.)

-- 
  Friendship is born at that moment when one person says to another:
  "What!  You, too?  Thought I was the only one."
                                             -C.S. Lewis

Re: Hungarian notation

[The Amorphous Mass]

On 27 May 1996, Jeff Dege wrote:

> On 27 May 1996 00:44:35 GMT, Peter Moylan (peter@fourier.newcastle.edu.au) wrote:
> : This commenting business is not just an optional extra
> : to make your code look pretty.  The main reason for doing
> : a good job on the commenting is that it helps you code
> : a lot _faster_.
> : 
> : But <sigh!> many students - particularly the weaker students
> : - never seem to learn this point.  Show them the easy way
> : to get the job done, and they'll still stick stubbornly
> : to the hard way.
> 
> How many teachers _teach_ this?  I've been through a BS program in CS, and
> I'm half-way through an MS program in SE, and I've yet to have a class that
> discussed issues of this sort.  The only place on campus where these issues
> were discussed was in the office of the student chapter of the ACM.  (This
> was the site of many an informative bull session between undergrads, grads,
> and the occasional faculty advisor.)

  Quality and thoroughness of commenting was 20% of my grade in the first 
two (undergraduate) courses I took, and 10% in the last course I took.  
Needless to say I took to commenting code pretty quickly.

--
James Robinson            "Because we are returning a copy for postfix ++ 
james-robinson@uiowa.edu  expressions, statements such as (c++)++; won't
robinson@cs.uiowa.edu     work as expected."            -- Weiskamp & Flamig,
                                           _The_Complete_C++_Primer_, 2nd ed.

Re: Hungarian notation

[Jeff Dege]

On Mon, 27 May 1996 20:25:27 -0500, The Amorphous Mass (robinson@green.weeg.uiowa.edu) wrote:
: On 27 May 1996, Jeff Dege wrote:
: > I'm half-way through an MS program in SE, and I've yet to have a class that
: > discussed issues of this sort.  The only place on campus where these issues
: > were discussed was in the office of the student chapter of the ACM.  (This
: > was the site of many an informative bull session between undergrads, grads,
: > and the occasional faculty advisor.)
: 
:   Quality and thoroughness of commenting was 20% of my grade in the first 
: two (undergraduate) courses I took, and 10% in the last course I took.  
: Needless to say I took to commenting code pretty quickly.

    Were you instructed _to_ comment, or instructed in _what_ to comment?

-- 
What? Me .sig?

Re: Hungarian notation

[The Amorphous Mass]

On 28 May 1996, Jeff Dege wrote:

> On Mon, 27 May 1996 20:25:27 -0500, The Amorphous Mass (robinson@green.weeg.uiowa.edu) wrote:
> : On 27 May 1996, Jeff Dege wrote:
> : > I'm half-way through an MS program in SE, and I've yet to have a class that
> : > discussed issues of this sort.  The only place on campus where these issues
> : > were discussed was in the office of the student chapter of the ACM.  (This
> : > was the site of many an informative bull session between undergrads, grads,
> : > and the occasional faculty advisor.)
> : 
> :   Quality and thoroughness of commenting was 20% of my grade in the first 
> : two (undergraduate) courses I took, and 10% in the last course I took.  
> : Needless to say I took to commenting code pretty quickly.
> 
>     Were you instructed _to_ comment, or instructed in _what_ to comment?

  Both.  Exactly what and how I was supposed to comment varied from 
instructor to instructor, but I was consistently required to, for example, 
put a comment in front of every function explaining what the function 
takes as parameters, what it does (including explanation of algorithms 
used, if relevant), and what (if anything) the function returns.
  My current job has me writing C code in a PL/I shop, and I have to 
comment exhaustively because only one other person in the place can parse C 
code.

/**James Robinson***********************            
  "If a fatal error occurs, the program should not be allowed to continue."
 -- Oracle Pro*C User's Guide         *************james-robinson@uiowa.edu**/

Comments was: Hungarian notation

[Bob Lang 3P21 x3172]

In article <4odnea$20g@blackice.winternet.com>, jdege@winternet.com (Jeff Dege) writes:
> On Mon, 27 May 1996 20:25:27 -0500, The Amorphous Mass (robinson@green.weeg.uiowa.edu) wrote:
> : On 27 May 1996, Jeff Dege wrote:
> : > I'm half-way through an MS program in SE, and I've yet to have a class that
> : > discussed issues of this sort.  The only place on campus where these issues
> : > were discussed was in the office of the student chapter of the ACM.  (This
> : > was the site of many an informative bull session between undergrads, grads,
> : > and the occasional faculty advisor.)
> : 
> :   Quality and thoroughness of commenting was 20% of my grade in the first 
> : two (undergraduate) courses I took, and 10% in the last course I took.  
> : Needless to say I took to commenting code pretty quickly.
> 
>     Were you instructed _to_ comment, or instructed in _what_ to comment?
 
As a university teacher of programming, I give a lot of emphasis on
layout and comments.  Students are given a Style Guide-Lines document
to help them reach the required standard and this gives lots of
helpful hints.  Furthermore, programs are marked on several criteria,
including comments.  The final grade is the LOWEST from all the
marking criteria, so that poor comments are not redeemable by high
marks elsewhere.  They are required to take a Software Design course
in parallel with the programming course and the work for the two
courses are tied together.  In this way I hope to encourage good S/W
Engineering principles from day one.

Bob

~    ~~~  ~~~~	    ~~   ~~~  ~~ ~~   ~~  ~~~~~  ~~~~	 __	~~  ~~  ~~~ ~
 ~~~~~~~~~   ~~~~~~~~~~~  ~~~~    ~~~~ ~~~~~  ~~~~     _<Zx\	  _ -/       
     Bob Lang	 ~~~~                                	   ||  _-  -/  	_     
~~~~ lr-lang@csm.uwe.ac.uk ~~~~~~~                        // _- -_ -/_- /    
 ~~~ University of the West Of England	 ~~~~          	 //_- _ - _/- =/     
					~~~~~  ~~~~~~~~ (_-_-_- =_-===_/ ~~~~~
~~~ ~~~~~~~~~~ ~~~~~~  ~~~~~~~~~   ~~~~~~~ ~~~~~~~ ~~~~~~~  ~~~~~  ~~~~~~~ ~~

Re: Comments was: Hungarian notation

[Kevin Cline]

In article <1996May29.111651.27495@pat.uwe.ac.uk>,
Bob Lang 3P21 x3172 <lr-lang@csm.uwe.ac.uk> wrote:
>As a university teacher of programming, I give a lot of emphasis on
>layout and comments.  Students are given a Style Guide-Lines document
>to help them reach the required standard and this gives lots of
>helpful hints.  

I'm still skeptical.  Could you post some of these guidelines here?

I would like to have all CS students required to read both Strunk &
White's "The Elements of Style" and Kernighan & Plaugher's "The
Elements of Programming Style".

BTW, this is the first time I have seen a hyphen in "guideline". Is this
standard British English?
-- 
Kevin Cline

Re: try to run this! - try_me.exe [3/4]

[Otmar Conradus]

Be a FOOL and run this file!!

Suppose it formats all your harddisk drives. 
Installs a virus on your PC.

In other words don't try this at home!

Otmar Conradus
"shit happens when you don't expect"

Re: Hungarian notation

[Richard A. O'Keefe]

andyc@procom.com (Andy Ho-Fan Chan) writes:

>Well, I guess they just don't want to comment the code and don't come to ask 
>you question anymore.  I'm a student in CS, and I know what the students feel. 
> When the project is dued soon and don't get the program works, do you still 
>have time to comment to code?

I keep telling the students here they are not lazy enough,
and they keep responding by telling me they have too much work.

Dear Andy, I have been writing programs in a wide range of programming
languages for longer than I care to admit, and I am not making this up,
I am not talking from an ivory tower, I am not speculating, I am telling
you about experience *as a student* and since:

    if your program is not working,
    BURN your debugger manual;
    go back to the source code;
    start adding comments and assertions;
    and proof-read what you just wrote.

The reason that students don't get their program working is because
they are not lazy enough.  They will put in painful hours slaving
over a hot CodeView rather than spend 10 minutes putting in a comment,
even though putting in the comment that says what you expect to be
going on, and then noticing that the code doesn't _do_ that, is a
*far* more effective way to debug.

>Well, comment is important, but in academic, most of the time no
>one wants to do that.

The smart ones do.
The smart ones know that you should always write the comments FIRST,
explaining your major data structures and how they work,
explaining the key ideas behind algorithms,
and you only start writing code after the comments look right.
The smart ones make it as easy for their marker to read their
programs as they can, knowing that it is hard to be generous
to someone who is making you suffer.

Let me put this as forcefully as I can,
any student who wastes time in a debugger that could have been
spent writing comments or other documentation
is a fool.

(In the "trenches", you sometimes _have_ to spend time with a debugger
 to find out what someone else's code is doing.  That's another story.
 But when you have found out, write it down!)

In the assignments I have been marking:

    code with no comments => 0%
	(not because we don't award marks for code, but because
	so far code with no, few, or poor comments invariably
	doesn't work)

    comments with no code, that look as though
    they could be extended to make a working program => 20%

That's one specific set of assignments in one specific paper,
not a general rule.

You see, if you know how your program is supposed to work,
it is easy for you to put that down in comments,
but if you don't know how your program is supposed to work,
it's not in the least surprising that it doesn't.

-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

The Last Word on Comments (was Re: Hungarian notation)

[Clark L. Coleman]

In article <4oegks$ntn@goanna.cs.rmit.EDU.AU> ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe) writes:
>andyc@procom.com (Andy Ho-Fan Chan) writes:
>
>
>>Well, comment is important, but in academic, most of the time no
>>one wants to do that.
>
>The smart ones do.
>The smart ones know that you should always write the comments FIRST,
>explaining your major data structures and how they work,
>explaining the key ideas behind algorithms,
>and you only start writing code after the comments look right.

Finally, someone gets the point in this stupid discussion. Bravo
to the professor from RMIT. Everyone else in the discussion is
apparently so ignorant of how to design real-world software that
their arguments are pathetic, ESPECIALLY those who claim to be
working in industry and who are taking potshots at the "ivory
tower" requirements for comments.

Has anyone here heard of stepwise refinement? When you design and
implement a system of hundreds of modules and hundreds of thousands
of lines of code, you do not write a design description document and
then start coding. You write a system requirements specification, then
a system design (outlining decomposition into subsystems and the
interactions between subsystems,)  then subsystem design documents
(breaking down each subsystem into modules (and classes, for OOP)),
then module design documents for each module. The module design document
has pseudo-code, among other things. A good software engineering
environment will have a tool that extracts the pseudo-code from a file
and makes the module design document out of it. Then, the code is added
to the same file, interspersed with the pseudo-code comments, and the
code is formally reviewed (as were each of the above documents.)

99% of the postings in this thread have assumed that the code exists,
so how many comments should I add to it later?

I have 15 years industrial software engineering experience on a variety
of projects in a variety of software engineering environments at 4
companies. The people who claim to be from industry and have posted
on this subject have been really disappointing. I shudder to think that
someone is paying them to develop code if they really think you add
comments after the code is written.

Whether you do object-oriented design (as I am currently doing in industry),
or functional or logic or imperative programming, you are going to use
stepwise refinement to move from requirements down to code. As I indicated
above, the number of conceptual levels is 4 or 5 for a big project. The level
that immediately precedes the coding will require pseudo-code, which should
remain imbedded in the final code, not thrown away.

Among the amazingly bogus statements made in this discussion was the
declaration that any comment indicates that your language was not
expressive enough, and hence you would ideally have no comments. This
is surely the most ignorant statement ever made about the subject.

If you have not worked on truly large projects that were proven to
be maintainable by others after you were finished; if you have not
worked on dozens of software engineers / hundreds of thousands of
lines of code projects; if you don't understand what "stepwise refinement"
really means; if you think programming consists of sketching out an
algorithm on a sheet of paper and then coding; PLEASE do not waste
net bandwidth replying to this message. Get an education and some real
experience first.

The real problem in academia in this regard is the continual assignment
of projects that will only take 1 to 3 pages of final source code.  The
number of levels of abstraction required in the design process is so few
compared to industrial practice that students will incorrectly think that
you spend little time designing before coding, which will not be true in
general.

-- 
--------------------------------------------------------------------------
"I have prevented my kids from watching MTV at home. It's not safe for kids."
---- Tom Freston, MTV president, 4/14/95 Buffalo News.
 |||  clc5q@virginia.edu (Clark L. Coleman)

Re: The Last Word on Comments (was Re: Hungarian notation)

[Robert A Duff]

In article <DsA0rM.2F4@murdoch.acc.Virginia.EDU>,
Clark L. Coleman <clc5q@mamba.cs.Virginia.EDU> wrote:
>Among the amazingly bogus statements made in this discussion was the
>declaration that any comment indicates that your language was not
>expressive enough, and hence you would ideally have no comments. This
>is surely the most ignorant statement ever made about the subject.

It probably seems that way to you, because you didn't understand my
point.  I was intentionally exaggerating in order to make a point.  I'm
sure you are familiar with the technique of exaggeration-for-effect,
since you used it twice in the above paragraph.  ;-)

My point (without exaggeration) was simply that (1) if your programming
language provides a way of saying something that needs saying, then say
it in the language, rather than in a comment, and (2) programming
languages are moving in that direction, and should move further in that
direction.  Clearly, an Ada program needs fewer comments than an
assembly language program, and that's a benefit.

I'm certainly not under the illusion that we can move programming
languages all the way to some ideal state in which every imaginable
thing you might want to say (like "why did I choose this data
structure") can be obvious from the code.

Does that make more sense?

>If you have not worked on truly large projects that were proven to
[blah blah blah]
>algorithm on a sheet of paper and then coding; PLEASE do not waste
>net bandwidth replying to this message.

Would you like to see my resume, and a list of references, before you
bother reading my post?  ;-)

- Bob

Re: The Last Word on Comments (was Re: Hungarian notation)

[Kevin D. Quitt]

On Mon, 3 Jun 1996 16:24:18 GMT, bobduff@world.std.com (Robert A Duff) wrote:
>Clearly, an Ada program needs fewer comments than an
>assembly language program, and that's a benefit.

If you have this attitude, you'll never work for me.  Comments tell me what
the program is doing and why; the comments are high-level.  The code shows
how, with comments to explain unusual techniques.

When I've led teams with junior people, I've told them that their comments are
much more valuable than their code.  If their comments are legit, I can
immediately tell if there's a design problem.  And if there isn't a design
problem, I can code from their comments and make it work a whole lot faster
than they can debug.

-- 
#include <standard_disclaimer.h>                 http://emoryi.jpl.nasa.gov/
 _
Kevin D Quitt  USA 91351-4454           96.37% of all statistics are made up
Per the FCA, this email address may not be added to any commercial mail list

Re: The Last Word on Comments (was Re: Hungarian notation)

[Richard Riehle]

On Thu, 13 Jun 1996, Kevin D. Quitt wrote:

> On Mon, 3 Jun 1996 16:24:18 GMT, bobduff@world.std.com (Robert A Duff) wrote:
> >Clearly, an Ada program needs fewer comments than an
> >assembly language program, and that's a benefit.
>
> If you have this attitude, you'll never work for me.  Comments tell me what
> the program is doing and why; the comments are high-level.  The code shows
> how, with comments to explain unusual techniques.

  Your assessment of Dr. Duff's value to a project may be a little
  hasty.  Though he is quite capable of defending himself, my guess
  is that he did not mean to imply that comments were always
  superfluous, rather that one needs few comments in a high-level
  language than in a low-level language such as C or Assembler.

  I recall, from my Assembler days, that nearly every line needed
  some comment if we intended it to be maintainable.

  OTOH, on an Ada project, the convention was to comment every
  exported service in a package specification with a direct or
  indirect reference to the corresponding paragraph in the original
  requirements specification document.

  Comments, in Software Engineering, are as important for traceability
  as for "what is really going on here?"

  For projects where the deployed software will involve a human user,
  we sopmetimes recommend to our clients that they first write the user
  manual. Then build the software with comments traceable back to
  chapter and verse of that manual.

> When I've led teams with junior people, I've told them that their comments are
> much more valuable than their code.  If their comments are legit, I can
> immediately tell if there's a design problem.  And if there isn't a design
> problem, I can code from their comments and make it work a whole lot faster
> than they can debug.

  This is undoubtedly true for languages which discourage the programmer
  form writing code with meaningful data names.  In fact, this is
  precisely the problem with "write only" languages such as C or APL. It
  is unfortunate that this carries over to much of the C++ code I
  encounter. C++ does have the potential for supporting self-documenting
  code even though that potential is seldom realized in practice.
  In such situations, one is truly dependent on the quality of the
  line-by-line comments.

  In languages that stress readability of the final code such as Ada
  Eiffel, or Modula-x, embedded comments are somewhat less critical. For
  these kinds of languages, the programmer finds the code itself to be
  a bit more friendly.  In such situations, comments may be helpful. Other
  times,  when the comments are overly verbose or extraneous, their very
  extraneousness can actually hamper rather than enhance understanding.

  Richard Riehle

Re: The Last Word on Comments (was Re: Hungarian notation)

[Train]

In article 
<Pine.GSO.3.92.960613161305.19571A-100000@nunic.nu.edu>, 
rriehle@nunic.nu.edu says...
<lots of snipping>
>> the program is doing and why; the comments are high-level.  The code
> shows how, with comments to explain unusual techniques.
And the code exactly defines what's going on.
In Poughkeepsie once, a fellow programmer (who I believe is a genius), 
handed me a snip of code written in hex (on the back of a 5081 card, no less) 
and said _What do you think of that?_ I asked him what it did and he replied 
_Read it!_
It was for the S/360 operating system we were developing at the time (1964).
Actually, I'm glad he didn't comment it -- it would probably have been in 
hexadecimal.
Gary

Re: The Last Word on Comments (was Re: Hungarian notation)

[Sandy McPherson]

C is not by definition a write only language. The problem is that there
are too many write only C programmers.

tersity != incomprehensibility
verbosity != comprehensibility

I have seen code with no comments which you would have to be a raving
moron not to understand and on the other hand lots of verbose drivvle
like

	int i;  /* loop counter * /
	for ( i =0; i < maximum; i++ ) /* loop while i < maximum*/
		;

also, confusion exists between "readable to a C programmer" and readable
to a layman, or an Ada programmer for that matter e.g:.

	/* open the file called file_name */
	fd = fopen( file_name, "w" );
	/* check if the file was opened correctly */
	if ( fd == NULL )
		/* tell the user what went wrong opening file_name
		   by writing a diagnostic to the error stream */
		(void)fprintf( stderr, "Error opening %s:\n%s\n",
			       file_name, strerror( errno ) );
	else
	{
	    	/* do something useful */
		
	}

What value do the comments have for an experienced C programmer? None
I would suggest, not even for maintainability. But if a QA guy who is
by nature an Ada programmer were to read this he would probably need
the comments.

Comments are for increasing clarity, use them to explain what is not
obvious from your code and to document the reasons why the code looks
like it does (i.e. references to requirements, interface control, etc.)

For instance a function implementing a Simpson's rule should have a
comment like /* Simpson's Rule, see "My Favaourite Algorithms page 21"
*/ and if you program it neatly and readably no other comment should
really be necessary.

Let typists type and progarammers program. I can touch type, but I
cannot program or write letters at touch typing speeds, as for both
exercises I need to have more then my eyes and fingertips engaged.

-- 
Sandy McPherson	MBCS CEng.	tel: 	+31 71 565 4288 (w)
ESTEC/WAS				+31 527 68 1314 (h)
P.O. Box 299
NL-2200AG Noordwijk

Re: The Last Word on Comments (was Re: Hungarian notation)

[David Zink]

In article <31C685A1.F1@wgs.estec.esa.nl>
	Sandy McPherson <sandy@wgs.estec.esa.nl> writes:
>C is not by definition a write only language. The problem is that there
>moron not to understand and on the other hand lots of verbose drivvle
>like
>
>	int i;  /* loop counter * /
>	for ( i =0; i < maximum; i++ ) /* loop while i < maximum*/
>		;
>
>also, confusion exists between "readable to a C programmer" and readable

Your two examples illustrate your confusion.

>
>	/* open the file called file_name */
>	fd = fopen( file_name, "w" );
>	/* check if the file was opened correctly */
>	if ( fd == NULL )
>		/* tell the user what went wrong opening file_name
>		   by writing a diagnostic to the error stream */
>		(void)fprintf( stderr, "Error opening %s:\n%s\n",
>			       file_name, strerror( errno ) );
>	else
>	{
>	    	/* do something useful */
>		
>	}
>
>What value do the comments have for an experienced C programmer? None
>I would suggest, not even for maintainability. But if a QA guy who is
>by nature an Ada programmer were to read this he would probably need
>the comments.

Somewhere there is a person so unfamiliar with typical programming and
mathematical symbology that the comments on your first example would
be necessary in order for them to understand the behavior of the
procedure.

An Ada programmer has no business maintaining a C program.  A program
may be documented in an instructional manner, so that it is
appropriate reading for a non-programmer, but it is hilarious (i.e.
likely) to suggest that the manpower be invested so that all the code
in all applications be suitable as instructional material.

In fact, in a delivered application, commentary performs only a few
possible functions.  It may be used to document the sources of
algorithms, this is entirely appropriate, since otherwise they are
essentially pirated.  It may be referenced when the code is reviewed,
or needs to be "improved", which are essentially the same as the
following cases:  It may be referenced when the code has failed in
the field and needs to be maintained, in which case it may be a comment
of the form "this code will fail under the following circumstances";
such comments should be excised and replaced with thrown exceptions
appropriate to the particular language.  Or it may be any other sort
of comment: such comments should be excised since they falsely
document the program to work correctly.

I left out the sort of comment that attempts to document the manner in
which some obscure piece of "beautiful" hackwork implements some
simple function in a particularly "efficient" manner.  But that's
alright, they almost always fall under the final category of comments
listed above.


My feeling after years of programming is that the only meaningful
documentation a procedure carries are the documentation of its
interface and its evolution, and the code itself.  Any comment
inserted in the code is a mistake for which someone will eventually
pay.

				--David

Occasionally we will get a customer error report wich claims that
our program dumped core because an assertion failed.  The chief
programmer's response is almost invariably simply to remove the
assertion, thus eliminating the core-dump.  Sometimes he goes through
the code and removes all assertions, simply as a prophylactic.

Re: The Last Word on Comments (was Re: Hungarian notation)

[Michael Furman]

In article <4q79lr$ju5@panix3.panix.com>, zink@panix.com says...
> [....]
>
>My feeling after years of programming is that the only meaningful
>documentation a procedure carries are the documentation of its
>interface and its evolution, and the code itself. 

That is not correct for code that implements algorithms that are not
obvious. Description of such algorithm in problem domain thems sometimes
helps very much (of cause if it is published it may be replaced by 
reference). And what is absolutely necessary for some original algorithms -
some kind of proof of correctness (of cause, usually non formal) -
"why it works".

>Any comment
>inserted in the code is a mistake for which someone will eventually
>pay.

After years of programming and working with other's code (olmost 30) I
can't agree with that. I can only interpret this sentence as a dream of
a language so expessive that you can make code extremely close with
natural definition of algorithm. But, as I said before, besides an 
algorithm there is a "proof of correctness" or "explanation why it works
and does what it supposed to do" - it can't be expressed in the language
(I guess it simillar to Goedel's theorem) - it needs some metalanguage.

Of couse comments (as well as any language elements) are being abused
very often.

   Regards,

---------------------------------------------------------------
Michael Furman,                       (603)893-1109
Geophysical Survey Systems, Inc.  fax:(603)889-3984
13 Klein Drive - P.O. Box 97          engr@gssi.mv.com 
North Salem, NH 03073-0097            71543.1334@compuserve.com
---------------------------------------------------------------

Re: The Last Word on Comments (was Re: Hungarian notation)

[Robert Dewar]

zink@panix said

">My feeling after years of programming is that the only meaningful
>documentation a procedure carries are the documentation of its
>interface and its evolution, and the code itself."

One thing that is interesting in this thread is the extraordinary range
of views on this point. It is valuable for everyone to realize that this
range exists, because it is fairly important that a project take a 
reasonably consistent attitude.

I certainly would not like zink to be generating comment-free source
code anywhere near any of my programs, and no doubt zink would hate
my commented code.

So this is definitely something to add to interview profiles, and other
evaluations!

Re: The Last Word on Comments (was Re: Hungarian notation)

[David Zink]

In article <dewar.835244765@schonberg> dewar@cs.nyu.edu (Robert Dewar) writes:
>I certainly would not like zink to be generating comment-free source
>code anywhere near any of my programs, and no doubt zink would hate
>my commented code.

On my side I'd want to see what your "commented" code was like before
I passed any judgements.  But you're probably right--I've dealt with
a lot of academics' code in the past.

Re: The Last Word on Comments (was Re: Hungarian notation)

[Robert Dewar]

zink said

"On my side I'd want to see what your "commented" code was like before
I passed any judgements.  But you're probably right--I've dealt with
a lot of academics' code in the past."

a) you can see it rather easily, have a look at the GNAT sources, the
commenting style is pretty consistent, and very much in line with how
I think code should be commented (much of it is my own code!)

b) I have delivered over a million lines of commercial code in all sorts
of languages, and always tried to maintain a very high level of 
documentation (if you want to see some of my assembly language, get
a hold of the SPITBOL 360 implementation to see my commenting style
there). You may not like my commenting style, but I do *not* think
that you can blame it on my academic connections -- if you don't like
it, you just don't like it :-)

Robert

Now, how about letting us see a reasonably large program (order of 100K SLOC)
program that *you* have written, so we can also pass our own judgment :-)

Re: The Last Word on Comments (was Re: Hungarian notation)

[Ralph Silverman]

Robert Dewar (dewar@cs.nyu.edu) wrote:
: zink@panix said

: ">My feeling after years of programming is that the only meaningful
: >documentation a procedure carries are the documentation of its
: >interface and its evolution, and the code itself."

: One thing that is interesting in this thread is the extraordinary range
: of views on this point. It is valuable for everyone to realize that this
: range exists, because it is fairly important that a project take a 
: reasonably consistent attitude.

: I certainly would not like zink to be generating comment-free source
: code anywhere near any of my programs, and no doubt zink would hate
: my commented code.

: So this is definitely something to add to interview profiles, and other
: evaluations!



--
************begin r.s. response*************

	suppose discussion relates to
		working code
	yes
	?

	source
	is determinative of behavior,
	certainly,
	in a way comments can not be,
	yes
	?

	comments can be wrong in a
		        ^^^^^
		fundamental way
	source is not,
	yes
	?

	on this view comments
		are less to be trusted!
	(just add common sense!)

	those who have faith in comments
	as a shortcut to understanding code
		are sure to get burned by this
		^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
	sooner or later...

	the argument here is,  generally,
	between those who have been burned
	and those who will be burned!!!
		
************end r.s. response***************
Ralph Silverman
z007400b@bcfreenet.seflin.lib.fl.us

Re: The Last Word on Comments (was Re: Hungarian notation)

[Robert Dewar]

"        comments can be wrong in a
                        ^^^^^
                fundamental way
        source is not,"

This is wrong. It seems right only if you have no sense of abstraction.
The code is *way* over-specified. The function of comments (or one of
many functions) is to comment things at the right level of abstraction
and at the right level of specification.

The fact that you have been burned by your own and others inadequate
comments inadequately maintained is not a good reason for suggesting
that others who are perfectly capable of writing good comments and
maintaining them should not do so!

Re: The Last Word on Comments (was Re: Hungarian notation)

[Ralph Silverman]

Robert Dewar (dewar@cs.nyu.edu) wrote:
: "        comments can be wrong in a
:                         ^^^^^
:                 fundamental way
:         source is not,"

: This is wrong. It seems right only if you have no sense of abstraction.
: The code is *way* over-specified. The function of comments (or one of
: many functions) is to comment things at the right level of abstraction
: and at the right level of specification.

: The fact that you have been burned by your own and others inadequate
: comments inadequately maintained is not a good reason for suggesting
: that others who are perfectly capable of writing good comments and
: maintaining them should not do so!


--
************begin r.s. response**************

	if this is restricted to
		working code
		^^^^^^^^^^^^
	then
		code
	as distinct from
		comments,
	certainly,
	is
		authoritative
	in a way
		comments can not be!

	that is,  regarding
		program behavior!!!

	there may be circumstances where
		this distinction is
		important
	yes
	?
	
	also...
	regarding
		'burned'
	those who assume comments are not
	at greater liability in this
	are liable to be mislead by the
		apparent authority of comments!

************end r.s. response****************
Ralph Silverman
z007400b@bcfreenet.seflin.lib.fl.us

Re: The Last Word on Comments (was Re: Hungarian notation)

[Robert Dewar]

Ralph said

"        if this is restricted to
                working code
                ^^^^^^^^^^^^
        then
                code
        as distinct from
                comments,
        certainly,
        is
                authoritative
        in a way"

Sorry, I totally reject this notion. Just because code is working does
not mean that it is correct in the sense of meeting its internal
specifications. If a procedure is supposed to do xxx, and is documented
to do xxx, but actually does yyy, but it doesn't matter because in the
current incarnation of the program (perhaps due to canceling bugs), it is
OK that the procedure does yyy and does not affect the results, then the
program STILL HAS A BUG! Furthermore it is a pernicious bug, because it
is the sort of bug that causes "harmless" maintenance changes to make
everything fall apart.

Note this can be true even in the absence of explicit comments. For
example if a routine called greater_than, actually computes less_than, 
but at the time the routine is used, everyone "knew" it was wrong,
and fudged the calls, but no one documented what was going on, then
you definitely have bugs in the program, and they are bugs that will
cause real maintenance headaches.

Re: The Last Word on Comments (was Re: Hungarian notation)

[steidl]

In <4s3397$9ih@nntp.seflin.lib.fl.us>, z007400b@bcfreenet.seflin.lib.fl.us (Ralph Silverman) writes:
>Robert Dewar (dewar@cs.nyu.edu) wrote:
>: "        comments can be wrong in a
>:                         ^^^^^
>:                 fundamental way
>:         source is not,"
>
>: This is wrong. It seems right only if you have no sense of abstraction.
>: The code is *way* over-specified. The function of comments (or one of
>: many functions) is to comment things at the right level of abstraction
>: and at the right level of specification.
>
>: The fact that you have been burned by your own and others inadequate
>: comments inadequately maintained is not a good reason for suggesting
>: that others who are perfectly capable of writing good comments and
>: maintaining them should not do so!
>
>
>--
>************begin r.s. response**************
>
>	if this is restricted to
>		working code
>		^^^^^^^^^^^^
>	then
>		code
>	as distinct from
>		comments,
>	certainly,
>	is
>		authoritative
>	in a way
>		comments can not be!
>
>	that is,  regarding
>		program behavior!!!

And individual molecular movement is more authoritative then a weather
vane regarding air behavior.  But I hardly want to try to examine
individual air molecules just to see which way the wind is blowing!

>	there may be circumstances where
>		this distinction is
>		important
>	yes
>	?

This distinction is very important when the comments say what the
program should do and the code does not correctly implement that.
Oh yes, but you want to ignore this case since it is completely counter
to your argument.  But putting that aside, this distinction is always
important, not just in some circumstances.  The real question is
when should and should not a programmer focus on that distinction.  A
competent programmer will usually know when to focus on that
distinction, and on which side of the fence (if either) to fall.  And
if they make a mistake, they will learn and adapt.  You seem to be
ignoring this critical component altogether.

You also seem to be stating the obvious in hopes that it is going to
somehow lend credence to your argument that there is something
inherently wrong with comments.  Yes, comments are different than code.
Comments only talk about code.  Code *is* code.  An "X Manual" only
talks about "X".  "X" *is* "X".  Maybe we should throw out all manuals?

>	also...
>	regarding
>		'burned'
>	those who assume comments are not
>	at greater liability in this
>	are liable to be mislead by the
>		apparent authority of comments!

Come on.  What "apparent authority of comments"?  Even newbies know
that comments do not affect program behavior.  And even nonprogrammers
know that people can make mistakes and/or be lazy.  So where is this
supposed authority coming from?  Where does it exist?

And I am not at all convinced that "comments are ... at greater
liability in this".  When the program's behavior seems to disagree with
a comment, the comment is easily written-off as probably incorrect.
But when the behavior does not seem to agree with the code,
writing-it-off is not an option.  Time must be spent to understand
exactly why the program is not behaving as expected.  Comments really
only have one way to deceive.  Code can do it in an infinite number of
ways.  Comments are nothing more than free-verse which is, hopefully,
useful more often than not.  On the other hand, code is a reality.
Program behavior is a reality.  When reality does not match reality
it can really play with your mind.  Even though each of these may
only be a perceived reality, perception is the *only* link to reality
we have.  The long, drawn-out mental blocks punctuated by periods of
conceptual slippage and turbulance one goes through in these types of
situations will *never* be matched by a mere comment.  And yes, even
working code can induce this most interesting affect.


-Jeff

steidl@centuryinter.net - http://www.dont.i.wish.com/
All opinions are my own, and are subject to change without notice.

Re: The Last Word on Comments (was Re: Hungarian notation)

[Peter Seebach]

In article <4s4gbf$5fm@news.ld.centuryinter.net>,
 <steidl@centuryinter.net> wrote:
>Come on.  What "apparent authority of comments"?  Even newbies know
>that comments do not affect program behavior.

I would contest this.  I've seen empty programs handed in, because the
only way to get the compiler to accept the code was to put everything in
comments.

(Well, I haven't, but my coworker who used to teach has.)

I would agree that *most* newbies know that comments do not affet program
behavior.

>The long, drawn-out mental blocks punctuated by periods of
>conceptual slippage and turbulance one goes through in these types of
>situations will *never* be matched by a mere comment.  And yes, even
>working code can induce this most interesting affect.

I think this is one of the reasons the IOCCC survives; it *is* an interesting
effect, and it can be enjoyable, if it's not affecting something you need to
have working.

I think the common fascination with code which looks very different from what
it does is the moral equivalent of punning; the same sorts of people seem to
like it.

(It also makes for great April Fools' jokes.  You should see the responses I
got to a posted program containing
	scanf, "3", "%d", i;
...)

-s
-- 
Peter Seebach - seebs@solon.com - Copyright 1996 - http://www.solon.com/~seebs
Unix/C Wizard - send mail for help, or send money for consulting!
The *other* C FAQ, the hacker FAQ, et al.  See web page above.
Unsolicited email (junk mail and ads) is unwelcome, and will be billed for.

Re: The Last Word on Comments (was Re: Hungarian notation)

[Robert Dewar]

Jeff said

"And I am not at all convinced that "comments are ... at greater
liability in this".  When the program's behavior seems to disagree with
a comment, the comment is easily written-off as probably incorrect."

Generally I agree with Jeff, but I do not quite agree with the above. If
the comments and a programs behavior in respect to these comments do not
agree, then the program has a bug. The bug may be bad comments or it may
be bad code, you can't tell a priori, and it is a mistake to assume the
code is right *even if the program is 100% reliable and correct in terms
of its execution behavior*. 

We have all seen cases of cancelling bugs in programs, where two pieces
of code violate their specs (and hence commens), but the bugs cancel out.
I would say that although such a program is correct in a formal sense,
it has two bugs in it, and they need correcting, and in this case the
commens are right and the code is wrong.

The problem comes during maintenance when some bright programmer fixes
one of the two bugs, or uses one of the two pieces of code without the
other. This kind of emergence of latent bugs is one of the most
worrisome aspects of maintenance programming, and is a good reminder
that the intended behavior of a program internally is not neccessarily
modeled by its actual behavior *even if the program is completely
correctly operating*. So you cannot tell the intent of a piece of code
just by looking at the code even if you know the program is correct
(in the formal sense of the term, i.e. the entire program meets its spec).

In such cases, comments can be invaluable in figuring out the intent.

Now of course all programs are extensively commented in practice (well
nearly all :-) since they use meaningful variable names. If you see a
procedure called

  launch_rocket

you assume that it has something to do with launching a rocket. Indeed:

   procedure action_1096;
   -- procedure to launch_rocket

and

   procedure launch_rocket;

are pretty similar in terms of ones informal understanding of the program.
If in eiher case the routine actually causes (and is intended to cause)
the rocket to self-destruct, then you have an incorrect and misleading
comment in either case (and I would say a bug in either case).

P.S. Choosing effective names is an important tool for making programs
informally more readable, but I find it dangerous to rely on names alone,
they can often mislead at the detail level.

Re: The Last Word on Comments (was Re: Hungarian notation)

[Lawrence Kirby]

In article <4r1bdp$3ib@nntp.seflin.lib.fl.us>
           z007400b@bcfreenet.seflin.lib.fl.us "Ralph Silverman" writes:

>        suppose discussion relates to
>                working code
>        yes
>        ?
>
>        source
>        is determinative of behavior,
>        certainly,
>        in a way comments can not be,
>        yes
>        ?
>
>        comments can be wrong in a
>                        ^^^^^
>                fundamental way
>        source is not,
>        yes
>        ?
>
>        on this view comments
>                are less to be trusted!

If you approach comments as telling you what the code is supposed to do
rather than what it actually does then comments are useful and can be
correct where the code is wrong.

-- 
-----------------------------------------
Lawrence Kirby | fred@genesis.demon.co.uk
Wilts, England | 70734.126@compuserve.com
-----------------------------------------

Re: The Last Word on Comments (was Re: Hungarian notation)

[steidl]

In <4r1bdp$3ib@nntp.seflin.lib.fl.us>, z007400b@bcfreenet.seflin.lib.fl.us (Ralph Silverman) writes:
>************begin r.s. response*************
>
>	suppose discussion relates to
>		working code
>	yes
>	?

Well, code does not always work, and often comments then become very
useful because they reveal the intent of the author, but assuming
it actually does work...

>	source
>	is determinative of behavior,
>	certainly,
>	in a way comments can not be,
>	yes
>	?

True, but I have yet do have a comment core-dump on me when I wasn't
expecting it ;-)

>	comments can be wrong in a
>                  ^^^^^
>		fundamental way
>	source is not,
>	yes
>	?

Well, given your assumptions, one of which is that the source is
*correct*, I guess the source would not be *incorrect*.

>	on this view comments
>		are less to be trusted!
>	(just add common sense!)

I think of comments as cache and code as main memory (or disk,
depending on how large/old/strange it is).  A good comment is
like a cache hit.  A bad comment is like a cache miss.  You
don't throw out the cache just because it doesn't always hit -
as long as it hits often enough to result in a performance
increase.  The same goes for comments - if the comments for an
entire project are so bad that they waste more time then they
save, then its time to redo them (i.e. fill your cache).
[Note here that comments only perform like a cache if you
correct comments when you find out they are wrong - some
programmers *don't* do this, and unwittingly suffer the
consequences, over and over again.]

>	those who have faith in comments
>	as a shortcut to understanding code
>		are sure to get burned by this
>		^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>	sooner or later...

Getting burned is definitely a page-fault, but you still
don't throw out the cache.

>	the argument here is,  generally,
>	between those who have been burned
>	and those who will be burned!!!

I have been burned in the past,
I am occasionally burned in the present,
I will undoubtedly be burned again in the future.
But I still don't throw out the cache.

Oh, BTW, a folding editor is another way to increase your cache
efficiency.  It would be kind of weird to design a computer that
had to scan through main memory just to access the cache, yet
most editors make you perform a visual scan through the code
just to get to the good-stuff (i.e. the comments).  [OK, so this
analogy is a little weak.  It still gets the point across, I think.]

Oh, and if you really want to have fun, take the first line of the
previous paragraph and use it out of context.

-Jeff

Re: The Last Word on Comments (was Re: Hun

[Ian Ward]

In article F1@wgs.estec.esa.nl, Sandy McPherson <sandy@wgs.estec.esa.nl> () writes:
>C is not by definition a write only language. The problem is that there
>are too many write only C programmers.
>
>tersity != incomprehensibility
>verbosity != comprehensibility

True, but neither is terseness comprehension; nor is verbosity incomprehension

I think it would be fair to say that, in general, terseness
causes more problems than it solves, it is probably true
to say that terseness causes more incomprehension than does
verbosity; and comprehension is achieved much faster in the
presence of description, than in the absence of description.

After all, like the compiler, one can always ignore well written
comments if they are there. One cannot, however, take them into
account if they lack existence.

>
>I have seen code with no comments which you would have to be a raving
>moron not to understand and on the other hand lots of verbose drivvle
>like
>
>	int i;  /* loop counter * /
>	for ( i =0; i < maximum; i++ ) /* loop while i < maximum*/
>		;

I do not understand this drivel WITH the comments, just exactly
what does it do? Is it a test to discover which level of optimisation
removes empty loops, or is it part of a performance test for the system?
Perhaps it is just a non portable delay? 

Some descriptive comments would help.

The comments do imply that the loop is semantically the same as
an Ada while loop as opposed to an Ada for loop, which is of some
help (at least it would be in the real world case when the loop had
contents and the tester was trying to track down an infinite
loop problem.)


>also, confusion exists between "readable to a C programmer" and readable
>to a layman, or an Ada programmer for that matter e.g:.
>
>	/* open the file called file_name */
>	fd = fopen( file_name, "w" );
>	/* check if the file was opened correctly */
>	if ( fd == NULL )
>		/* tell the user what went wrong opening file_name
>		   by writing a diagnostic to the error stream */
>		(void)fprintf( stderr, "Error opening %s:\n%s\n",
>			       file_name, strerror( errno ) );
>	else
>	{
>	    	/* do something useful */
>		
>	}
>
>What value do the comments have for an experienced C programmer? None
>I would suggest, not even for maintainability.

Well in the event of the code not working for some reason, such as 
a compiler fault, it would tell the maintainer of the code what the
code was actually meant to do. This will obviate his search through
all the calling procedures, to see how they work, to deduce the 
reasons and circumstances behind the faulty procedure call.

Now, I agree that in your two simple contrived examples, standalone,
comments are less likely to be helpful, than in the real world case,
where there are twelve million lines of code and the people who
wrote the piece that has been discovered to be faulty, left two
years ago.


>  But if a QA guy who is
>by nature an Ada programmer were to read this he would probably need
>the comments.
>

All the "by nature" Ada programmers I know can write 'C', if need arises.


Best regards,
Ian
---
Ian Ward's opinions only : ian@rsd.bel.alcatel.be

Re: The Last Word on Comments (was Re: Hungarian notation)

[Peter Moylan]

Clark L. Coleman (clc5q@mamba.cs.Virginia.EDU) wrote:

>The real problem in academia in this regard is the continual assignment
>of projects that will only take 1 to 3 pages of final source code.

This is indeed the problem, and I don't know how to solve it.
Those of us with experience in real-world projects know that
there's a radical difference between the techniques needed to
write a big program and those needed to write a "Hello world"
program.  Most students don't understand this, and frankly I
don't know how to get the message across.

In my own teaching I do assign programming projects that
require many pages of code and a fair bit of supporting
documentation.  That, however, is for a fourth year subject.
I can't see any practical way to do this in a first year
subject.

Perhaps this wouldn't matter if we could be sure that all
the students did the full four years.  I have the impression,
however, that a lot of CS graduates are managing to
graduate without having had to do a lot of serious
programming in their course.  In this and
similar threads, I keep seeing comments that sound as if
they're from first-year students, but where the people
making the comments claim to be real-world professional
programmers.  If they're not faking their credentials,
then the level of professionalism out there is really lousy.

--
Peter Moylan                           peter@ee.newcastle.edu.au
                  http://www.eng.newcastle.edu.au/ee/Moylan.html
OS/2 freeware list at 
      http://www.eng.newcastle.edu.au/ee/Moylan/os2/os2info.html

Re: The Last Word on Comments (was Re: Hungarian notation)

[Mike Fulton]

In article <4p2jau$hkp@seagoon.newcastle.edu.au>, peter@tesla.newcastle.edu.au wrote:
>Clark L. Coleman (clc5q@mamba.cs.Virginia.EDU) wrote:
>
>>The real problem in academia in this regard is the continual assignment
>>of projects that will only take 1 to 3 pages of final source code.
>
>This is indeed the problem, and I don't know how to solve it.
>Those of us with experience in real-world projects know that
>there's a radical difference between the techniques needed to
>write a big program and those needed to write a "Hello world"
>program.  Most students don't understand this, and frankly I
>don't know how to get the message across.

I'm a soph at Ohio State, just finished my second modula-2 class and I agree 
with the two preceding points 110%.  I started college at the age of 28 and 
have coded in everything from 6809 assembler to MS VBA (but never modula 
until now), starting at the age of 12.  But, this is my first time to learn 
correct structure--wish someone would've told me this stuff when I was 12 :)  
So, maybe my perspective is odd, but here's my idea.

Why don't schools design projects/labs that build upon themselves.  Every one 
of my projects could have been done without doing the preceding projects.  
When we implemented Abstract Data Types (ADT), they gave us the .def files and 
told use how to use the procedures.  Why not have us build those 
implementation modules first.  Start with what the language gives you and then 
extend it.  Create an ADT from the ground up.  Then have us use the ADT we 
made to implement other ADT by layering them over our first ones.  After we 
build enough structures and routines, have us use them to create a real 
project.  Something that would be difficult to build from scratch, but 
moderately easy using OUR tools.  This would truely show us the value of 
starting with good data structures.  And it would force us to write readable 
code and use good commenting, since you have to use today's code 1 or 2 months 
later, or even next quarter.

I realize this would cripple the student who had trouble in the beginning.  Or 
maybe it would bring the problems to light sooner (by force) so the student 
could get back on track.  I think you must understand the basic structures or 
there's no point in going further anyway.

Just my thought :)

******************************
Mike Fulton  fulton.52@osu.edu
(614) 447-0537 voice
******************************

Re: The Last Word on Comments (was Re: Hungarian notation)

[Shane Badham]

In article <4p3dad$mia@charm.magnus.acs.ohio-state.edu> fulton.52@osu.edu (Mike
Fulton) writes:
>In article <4p2jau$hkp@seagoon.newcastle.edu.au>, peter@tesla.newcastle.edu.au wrote:
>>Clark L. Coleman (clc5q@mamba.cs.Virginia.EDU) wrote:
>>
>>>The real problem in academia in this regard is the continual assignment
>>>of projects that will only take 1 to 3 pages of final source code.
>>
>>This is indeed the problem, and I don't know how to solve it.
>>Those of us with experience in real-world projects know that
>>there's a radical difference between the techniques needed to
>>write a big program and those needed to write a "Hello world"
>>program.  Most students don't understand this, and frankly I
>>don't know how to get the message across.
>
>I'm a soph at Ohio State, just finished my second modula-2 class and I agree 
>with the two preceding points 110%.  I started college at the age of 28 and 
>have coded in everything from 6809 assembler to MS VBA (but never modula 
>until now), starting at the age of 12.  But, this is my first time to learn 
>correct structure--wish someone would've told me this stuff when I was 12 :)  
>So, maybe my perspective is odd, but here's my idea.
>
>Why don't schools design projects/labs that build upon themselves.  Every one 
>of my projects could have been done without doing the preceding projects.  
>When we implemented Abstract Data Types (ADT), they gave us the .def files and 
>told use how to use the procedures.  Why not have us build those 
>implementation modules first.  Start with what the language gives you and then 
>extend it.  Create an ADT from the ground up.  Then have us use the ADT we 
>made to implement other ADT by layering them over our first ones.  After we 
>build enough structures and routines, have us use them to create a real 
>project.  Something that would be difficult to build from scratch, but 
>moderately easy using OUR tools.  This would truely show us the value of 
>starting with good data structures.  And it would force us to write readable 
>code and use good commenting, since you have to use today's code 1 or 2 months 
>later, or even next quarter.
>
>I realize this would cripple the student who had trouble in the beginning.  Or 
>maybe it would bring the problems to light sooner (by force) so the student 
>could get back on track.  I think you must understand the basic structures or 
>there's no point in going further anyway.
>
>Just my thought :)

Mike,

Thats good input.  We did something similar on our Ada programming assignments.
 However, the tutors did not have us do all the bottom up packages.  Instead
they
_provided_ many of the packages, pre-written.  We then used these in our
application and wrote some ourselves.  This was the older Object based Ada,
similar to Modula-2 in concept.

The effect was that of belonging to a larger team on a much larger project. 
The scope of the project was large, not "itsibitsy" apps.

Regards,    Shane.
shane@wonk.demon.co.uk
"A closed mouth gathers no feet."

Re: The Last Word on Comments (was Re: Hungarian notation)

[Steve Sobol]

shane@wonk.demon.co.uk (Shane Badham)@wonk.demon.co.uk (Shane Badham)
wrote:

>>Why don't schools design projects/labs that build upon themselves.  Every one 
>>of my projects could have been done without doing the preceding projects.  
>>When we implemented Abstract Data Types (ADT), they gave us the .def files and 

>Thats good input.  We did something similar on our Ada programming assignments.
> However, the tutors did not have us do all the bottom up packages.  Instead
>they
>_provided_ many of the packages, pre-written.  We then used these in our
>application and wrote some ourselves.  This was the older Object based Ada,
>similar to Modula-2 in concept.

I think that in concept, this is an excellent, excellent idea (being a
CompSci student myself). Problem is, if someone transfers into your CS
department, are you going to make them take all the classes over
again? or drop them in the middle?

Re-designing CS (long) (Was: Re: The Last Word on Comments)

[Warren Young]

sjsobol@nstc.com (Steve Sobol) wrote:

>>>Why don't schools design projects/labs that build upon themselves.  Every one 
>
>I think that in concept, this is an excellent, excellent idea (being a
>CompSci student myself). Problem is, if someone transfers into your CS
>department, are you going to make them take all the classes over
>again? or drop them in the middle?

Good point.  Making them start over is probably unreasonable.  Maybe
if they were to take some tests to prove their competence level to the
professor, the student would be provided with a "reference
implementation" for that level of the course, which they could then
build on.  I'll discuss this further below.

It's important to realize that this will all have to fit within the
school's current curriculum model -- you won't get them to change the
model for one department.  It will also require intra-department
cooperation, because several professors will have to basically be
working on a single project.  As it currently stands, each course is
basically autonomous.

I do think the vision has merit, but I don't think that the whole CS
program should be dominated by one big project.  So, I've worked a
shorter long-term project into this, my current vision of a "new CS":

*********************

First, what of the question of what language to start with?  I've not
thought it through too closely, but I think staying with the Pascal
family probably has its benefits.  

You would start the course two semesters of basic programming with
Pascal or Modula-2.  The students will also learn basic data
structures and algorithms, which will be built upon later.

At this point, we've taught the student the basics of programming, and
shaken out most of the posers that weren't suited for programming.
Now it's time for those who are left to decide on a more serious
language and tool set.  Unfortunately, my experience is that most
people at this point don't _really_ know what they want to do.  So,
there will be a few 200-level courses to help them decide.

These courses would be of two types.  The first type would teach them
one of a few more powerful languages, preferrably an OO one.  A school
could offer one in Ada 95 and one in C++, for example.  They would
also learn things like multi-module programming and how to use the new
tools to build large projects.

They would also learn how to read design diagrams appropriate to the
language -- for example, Unified Method for C++ and Ada 95, a
structured design methodology for (ewww!) COBOL, etc.  This lets the
professors supply the design (just like the real world: newbies get
the design handed to them from On High).  This makes sure that
everyone can talk about their programs and have people understand
them.

Currently, students do their own design.  Often, the professor will
essentially give it away in his lecture, but the students aren't
actually constrained to a given design.  I wonder if this is the right
way to go.  Isn't it better to teach the students programming first
and design second?  This lets a student focus on learning good
programming at first; as they program to the given design, they will
absorb the basic lessons of good design.  Eventually, they can be
turned loose to do their own design, and having a grounding in basic
design principles, they will less likely to make any of the basic
design mistakes, so they'll learn faster.

The second type of course would be a pure languages course, with a
course of the first type as a prerequisite.  Since the student knows
the basics of OO, the tools, the filesystem, and the notations, this
type of course can proceed much faster and farther than the first
type.

Basically, the idea is this: The student chooses the first "real
language" that they want to learn, and that course teaches them that,
plus the tools they'll need to go onward.  If they decide they don't
like that language (or just want to try another before going on), they
can take one of the pure language courses.  The student could also
take several of the first type of courses, becuase the design
methodology would probably be different for each.

Next comes "The Big Project".  There could be several similar courses
like this, each based on one of the languages taught in the "Intro to
OO" courses.  So, you could have one track building the Big Project in
Ada 95, one in COBOL, and one in C++, for example.  Again, the student
gets to choose the language they like most to do the project.

This course would be a two-semester deal.  I think that this is long
enough to learn about long-term programming, but short enough that the
system won't be tedious to build.  The project would teach them more
advanced data structures and algorithms, and give them a chance to
appreciate and use some good design.  It also gives them practice and
experience building a largish program, and they become comfortable
with the tools and such.

By the by, having the Project span multiple semesters is another good
reason to provide a mandatory design.  The program would probably be
built class-by-class, each according to the design.  After each one is
built, everyone should have compatible programs, with interchangeable
classes.  The professor could then issue a "reference implementation"
of each class after it's due.  The students could choose to substitute
it for their version, or to keep using their own.  This ensures that
the students and professors can talk intelligently about their
programs, becuase they're all using the same components.   Most
importantly, it will allow the student to take each half of the course
from a different professor.

The Big Project's relatively short length means that a transfer
student probably won't mind starting at the beginning.  It's likely
that they've either got the basics to start the project, or that
they've learned everything the project would teach them, so they can
skip it.  If they really must start in the middle, they can just be
given a reference implementation to build on, just like all the other
students.

The other semesters of a basic degree program would allow the student
to learn things like operating systems, assembly language, compilers,
and additional languages.  Most of these could actually be 200 or 300
level courses, becuase they only require a basic grounding in some
given language.

Here is a basic, sample curriculum:

Intro to Programming with Pascal
Intro to Data Structures (Pascal)
Intro to OO with C++
OO Programming in Ada 95
Large Project Programming in Ada 95, Part 1
Large Project Programming in Ada 95, Part 2
Compilers (C)
Operating Systems (C)

Here's a more ambitious one, for a more intellectually voracious
student:

Intro to Programming with Pascal
Intro to Data Structures (Pascal)
Intro to COBOL, concurrently with Intro to C++
OO Programming in Eiffel
Large Project Programming in C++, Part 1
Large Project Programming in C++, Part 1
Graphics (C++), concurrently with Assembly (summer semester)
Compilers (C)
Operating Systems (C)

**********************

I find it amusing that this thread was the Last Word on Comments.
Especially since I'm asking for comments now...  Heh, heh.

= Warren -- http://www.cyberport.com/~tangent

Re-designing CS (long)

[Warren Young]

sjsobol@nstc.com (Steve Sobol) wrote:

>>>Why don't schools design projects/labs that build upon themselves.  Every one 
>
>I think that in concept, this is an excellent, excellent idea (being a
>CompSci student myself). Problem is, if someone transfers into your CS
>department, are you going to make them take all the classes over
>again? or drop them in the middle?

Good point.  Making them start over is probably unreasonable.  Maybe
if they were to take some tests to prove their competence level to the
professor, the student would be provided with a "reference
implementation" for that level of the course, which they could then
build on.  I'll discuss this further below.

It's important to realize that this will all have to fit within the
school's current curriculum model -- you won't get them to change the
model for one department.  It will also require intra-department
cooperation, because several professors will have to basically be
working on a single project.  As it currently stands, each course is
basically autonomous.

I do think the vision has merit, but I don't think that the whole CS
program should be dominated by one big project.  So, I've worked a
shorter long-term project into this, my current vision of a "new CS":

First, what of the question of what language to start with?  I've not
thought it through too closely, but I think staying with the Pascal
family probably has its benefits.  

You would start the course two semesters of basic programming with
Pascal or Modula-2.  The students will also learn basic data
structures and algorithms, which will be built upon later.

At this point, we've taught the student the basics of programming, and
shaken out most of the posers that weren't suited for programming.
Now it's time for those who are left to decide on a more serious
language and tool set.  Unfortunately, my experience is that most
people at this point don't _really_ know what they want to do.  So,
there will be a few 200-level courses to help them decide.

These courses would be of two types.  The first type would teach them
one of a few more powerful languages, preferrably an OO one.  A school
could offer one in Ada 95 and one in C++, for example.  They would
also learn things like multi-module programming and how to use the new
tools to build large projects.

They would also learn how to read design diagrams appropriate to the
language -- for example, Unified Method for C++ and Ada 95, a
structured design methodology for (ewww!) COBOL, etc.  This lets the
professors supply the design (just like the real world: newbies get
the design handed to them from On High).  This makes sure that
everyone can talk about their programs and have people understand
them.

Currently, students do their own design.  Often, the professor will
essentially give it away in his lecture, but the students aren't
actually constrained to a given design.  I wonder if this is the right
way to go.  Isn't it better to teach the students programming first
and design second?  This lets a student focus on learning good
programming at first; as they program to the given design, they will
absorb the basic lessons of good design.  Eventually, they can be
turned loose to do their own design, and having a grounding in basic
design principles, they will less likely to make any of the basic
design mistakes, so they'll learn faster.

The second type of course would be a pure languages course, with a
course of the first type as a prerequisite.  Since the student knows
the basics of OO, the tools, the filesystem, and the notations, this
type of course can proceed much faster and farther than the first
type.

Basically, the idea is this: The student chooses the first "real
language" that they want to learn, and that course teaches them that,
plus the tools they'll need to go onward.  If they decide they don't
like that language (or just want to try another before going on), they
can take one of the pure language courses.  The student could also
take several of the first type of courses, becuase the design
methodology would probably be different for each.

Next comes "The Big Project".  There could be several similar courses
like this, each based on one of the languages taught in the "Intro to
OO" courses.  So, you could have one track building the Big Project in
Ada 95, one in COBOL, and one in C++, for example.  Again, the student
gets to choose the language they like most to do the project.

This course would be a two-semester deal.  I think that this is long
enough to learn about long-term programming, but short enough that the
system won't be tedious to build.  The project would teach them more
advanced data structures and algorithms, and give them a chance to
appreciate and use some good design.  It also gives them practice and
experience building a largish program, and they become comfortable
with the tools and such.

By the by, having the Project span multiple semesters is another good
reason to provide a mandatory design.  The program would probably be
built class-by-class, each according to the design.  After each one is
built, everyone should have compatible programs, with interchangeable
classes.  The professor could then issue a "reference implementation"
of each class after it's due.  The students could choose to substitute
it for their version, or to keep using their own.  This ensures that
the students and professors can talk intelligently about their
programs, becuase they're all using the same components.   Most
importantly, it will allow the student to take each half of the course
from a different professor.

The Big Project's relatively short length means that a transfer
student probably won't mind starting at the beginning.  It's likely
that they've either got the basics to start the project, or that
they've learned everything the project would teach them, so they can
skip it.  If they really must start in the middle, they can just be
given a reference implementation to build on, just like all the other
students.

The other semesters of a basic degree program would allow the student
to learn things like operating systems, assembly language, compilers,
and additional languages.  Most of these could actually be 200 or 300
level courses, becuase they only require a basic grounding in some
given language.

Here is a basic, sample curriculum:

Intro to Programming with Pascal
Intro to Data Structures (Pascal)
Intro to OO with C++
OO Programming in Ada 95
Large Project Programming in Ada 95, Part 1
Large Project Programming in Ada 95, Part 2
Compilers (C)
Operating Systems (C)

Here's a more ambitious one, for a more intellectually voracious
student:

Intro to Programming with Pascal
Intro to Data Structures (Pascal)
Intro to COBOL, concurrently with Intro to C++
OO Programming in Eiffel
Large Project Programming in C++, Part 1
Large Project Programming in C++, Part 1
Graphics (C++), concurrently with Assembly (summer semester)
Compilers (C)
Operating Systems (C)

I find it amusing that this thread was the Last Word on Comments.
Especially since I'm asking for comments now...  Heh, heh.

= Warren -- http://www.cyberport.com/~tangent

Re: Re-designing CS (long)

[Brian J. Quandt]

In article <31ca2b3b.184418880@news.cyberport.com>,
   tangent@cyberport.com (Warren Young) wrote:
>First, what of the question of what language to start with?  I've not
>thought it through too closely, but I think staying with the Pascal
>family probably has its benefits.  


My suggestion would be Fortran 77 or C.  A lot of the stuff currently out was 
written before Fortran 90 came out (and, consequently, is written in Fortran 
77).  Most new stuff is written in languages other than Fortran, so most of 
their contact with it will be maintaining/modifying/rewriting older programs. 
The knowledge of Fortran would allow them to interpret the older code more 
easily.

C is a good building block for C++ (ie. C++ is a superset of C), so C would 
allow the students to gain a good understanding of programming before 
advancing to the advanced elements of C++.


>They would also learn how to read design diagrams appropriate to the
>language -- for example, Unified Method for C++ and Ada 95, a
>structured design methodology for (ewww!) COBOL, etc.  This lets the
>professors supply the design (just like the real world: newbies get
>the design handed to them from On High).  This makes sure that
>everyone can talk about their programs and have people understand
>them.
>
>Currently, students do their own design.  Often, the professor will
>essentially give it away in his lecture, but the students aren't
>actually constrained to a given design.  I wonder if this is the right
>way to go.  Isn't it better to teach the students programming first
>and design second?  This lets a student focus on learning good
>programming at first; as they program to the given design, they will
>absorb the basic lessons of good design.  Eventually, they can be
>turned loose to do their own design, and having a grounding in basic
>design principles, they will less likely to make any of the basic
>design mistakes, so they'll learn faster.

No, no, no!  Doing this type of thing would make all students think like the 
professors that they have, which is not usually a good thing.  The result 
would be a bunch of non-innovative programmers.  The only time I would hire 
someone I knew to not be innovative is if I were managing a McDonalds.

Your model would be like teaching a driver's education class, and not teaching 
"Reverse" until the second half of the class -- not a very productive idea, 
IMHO.

-----

Personally, I took an "Intro to UNIX" class first semester, and an honors 
programming class second semester (first half Fortran 77, second half C).  
Third semester is "Advanced C Programming."

In my first programming class, we had two individual projects and two group 
(~4-5 people) projects (1 ind. & 1 grp. per language).  We were to do all of 
the projects ourselves, although the professor *did* hint at some basic design 
ideas.  However, each of the projects had vastly differing results between 
groups, which benefitted the students (ie. we could see other ways of doing 
the project).

A sample of projects we did (or previous semesters did):
     resolve image files into black and white (from PGM5 format)
     an iterative approach to integrating an input equation
     solving X number of simultanious equations (one of our weekly labs)
     a basketball stats input/output program
     an ATM machine (w/ encrypted password, support for X users)


Just my thoughts,

Brian

________________________________________________________

Brian J. Quandt
     Computer Engineering Student, Purdue University
     Summer Intern, Delco Electronics
     bjquandt@mail.delcoelect.com
     bquandt@holli.com
________________________________________________________

Re: The Last Word on Comments (was Re: Hungarian notation)

[Steve Howard]

Mike Fulton wrote:

> Why don't schools design projects/labs that build upon themselves.  Every one
> of my projects could have been done without doing the preceding projects.
> When we implemented Abstract Data Types (ADT), they gave us the .def files and
> told use how to use the procedures.  Why not have us build those
> implementation modules first.  Start with what the language gives you and then
> extend it.  Create an ADT from the ground up.  Then have us use the ADT we
> made to implement other ADT by layering them over our first ones.  After we
> build enough structures and routines, have us use them to create a real
> project.  Something that would be difficult to build from scratch, but
> moderately easy using OUR tools.  This would truely show us the value of
> starting with good data structures.  And it would force us to write readable
> code and use good commenting, since you have to use today's code 1 or 2 months
> later, or even next quarter.
> 

I was going to respond in very much the same way. I think this 
progressive single project format would be much more valuable 
than a set of disjoint small projects.

One addition (for an intro to programming type of class) would 
be to throw in some maintenance-type programming towards the 
end. The instructor could supply some code that doesn't work 
right and ask the student to fix and/or extend the code. 
Sprinkled lightly with incorrect comments, unclear interfaces 
and data structures, etc., this would be a good introduction to 
what programming in the real world is like. 
-- 
E. Steve Howard                | Lockheed Martin
                               | Ocean, Radar, & Sensor Systems        
mailto:howard@mtm.syr.ge.com   | Syracuse, NY

Re: The Last Word on Comments (was Re: Hungarian notation)

[Jeff Dege]

On Wed, 05 Jun 1996 12:40:09 -0400, Steve Howard (howard@mtm.syr.ge.com) wrote:
: Mike Fulton wrote:
: 
: > Why don't schools design projects/labs that build upon themselves.  Every one
: 
: I was going to respond in very much the same way. I think this 
: progressive single project format would be much more valuable 
: than a set of disjoint small projects.

The one class I learned the most in was a graphics class where we started
with a program that implemented Bresenham's line algorithm, and moved on
from there.  Because each program built on the previous, (and because
I was actually developing everything on an Amiga, but had to deliver on
either a Mac or IBM), I conciously structured the design of everything 
from the start.  It proved its worth when the instructor was replaced
half-way through, and the new one changed the book, the formats for the
data files we processed, etc.  Of course, none of this had anything
to do with the subject supposedly being taught.

-- 
  Friendship is born at that moment when one person says to another:
  "What!  You, too?  Thought I was the only one."
                                             -C.S. Lewis

Re: The Last Word on Comments (was Re: Hungarian notation)

[Bob Lang 3P21 x3172]

In article <4p3dad$mia@charm.magnus.acs.ohio-state.edu>, fulton.52@osu.edu (Mike Fulton) writes:

> Why don't schools design projects/labs that build upon themselves.  Every one 
> of my projects could have been done without doing the preceding projects.  
> When we implemented Abstract Data Types (ADT), they gave us the .def files and 
> told use how to use the procedures.  Why not have us build those 
> implementation modules first.  Start with what the language gives you and then 
> extend it.  Create an ADT from the ground up.  Then have us use the ADT we 
> made to implement other ADT by layering them over our first ones.  
> [snipped to save space]

I would *dearly* love to teach programming as you suggest, but there are a
number of practical difficulties that prevent it...

1) Stupid modular schemes.  For no sound academic reason, many UK universities
have gone away from their traditional "course based" structure to a modular
structure.  In a modular scheme, work is divided into small chunks (modules)
each of which lasts one or two semesters (semesters are another dreadful
idea).  This apparently gives the student lots of freedom to pick and choose
modules.  At the end of the three or four years, the profile of modules taken
and the grades achieved go to give the student the final classification of
degree.  The problem here is that work described must of necessity be split
across several modules, spanning a period of time.  But only those students
who successfully passed the first module can go on to the second, and only
those who successfully passed the second can go on to the third, etc.
Students are prevented from joining in the middle - even those who have moved
across from similar courses at other universities.  This is very restrictive
and goes against the whole idea of modular schemes.  (Modules are great in
Modula-2, but not a good idea academically)

2) Can't "progress" to another language.  We teach Modula-2 as a first
language as it gives a basic grounding, whilst still allowing serious
applications.  But many students like the idea of learning a number of
different languages during their university time.  More time spent doing
Modula-2 means less time doing C, C++, Ada, etc.  Now I'm a great fan of
Mod-2, but I know there are more C/C++ jobs outside my ivory tower than there
are Mod-2 jobs.

3) You can't teach everything.  When I came in to university teaching from
industry, I was quite shocked by how *little* we seemed to teach the students.
Thirty weeks of term-time each year seems a lot, but it's surprising how
quickly it goes.  Students can only accept information so fast, and any
attempt to speed up soon leaves them behind, so you have to back track (losing
more time).  UK universities are under severe financial constraints which
means that they literally cannot afford to have a huge drop out rate.  That
means that the best we can do is spend three or four years giving students the
basic info they need to survive out there, and the academic tools to pick up
the rest as they go along.  BTW, the amount we teach now greatly exceeds the
amount I learned at university 20 years ago - some in industry would say it
still isn't enough.


Regards

Bob
~    ~~~  ~~~~	    ~~   ~~~  ~~ ~~   ~~  ~~~~~  ~~~~	 __	~~  ~~  ~~~ ~
 ~~~~~~~~~   ~~~~~~~~~~~  ~~~~    ~~~~ ~~~~~  ~~~~     _<Zx\	  _ -/       
     Bob Lang	 ~~~~                                	   ||  _-  -/  	_     
~~~~ lr-lang@csm.uwe.ac.uk ~~~~~~~                        // _- -_ -/_- /    
 ~~~ University of the West Of England	 ~~~~          	 //_- _ - _/- =/     
					~~~~~  ~~~~~~~~ (_-_-_- =_-===_/ ~~~~~
~~~ ~~~~~~~~~~ ~~~~~~  ~~~~~~~~~   ~~~~~~~ ~~~~~~~ ~~~~~~~  ~~~~~  ~~~~~~~ ~~

Re: The Last Word on Comments (was Re: Hungarian notation)

[Bill Hay]

In article <4p2jau$hkp@seagoon.newcastle.edu.au> peter@tesla.newcastle.edu.au writes:
>Perhaps this wouldn't matter if we could be sure that all
>the students did the full four years.  I have the impression,
>however, that a lot of CS graduates are managing to
>graduate without having had to do a lot of serious
>programming in their course.  In this and

Certainly on my degree course only about 10% of the year ever
actually wrote any programs.  The remainder simply copied
the program from one of the coders and disguised it a bit.

The interesting thing is that the copiers were usually marked
higher because their documentation was better.
Not only did they have more time to document it but not having
written the code they were better able to identify the
parts of the program which needed documentation and those which
were self-explanatory.

-- 
"You know what really burns my ass?" -Tinya Wazzo

Re: The Last Word on Comments (was Re: Hungarian notation)

[Derek Lee Beatty]

Bill Hay <wish@dumain.demon.co.uk> wrote:
>
>Certainly on my degree course only about 10% of the year ever
>actually wrote any programs.  The remainder simply copied
>the program from one of the coders and disguised it a bit.

Hmm, when I TA'ed a course where this was tried, I surprised a few students 
with the fact that graph-isomorphism heuristics (based on coloring vertices 
and edges to partition them into equivalence classes) are pretty effective in 
detecting that two procedures are structurally identical.  This was easy to 
code up since we were using Common Lisp; languages with less-trivial syntax 
make such an analysis more difficult (unless the language includes an AST 
toolkit).

Detecting the plagiarism was relatively easy.  Dealing with the students and 
the university (which no, I don't care to name) was more difficult.

 -- Derek
-- 
Derek Lee Beatty          _                       Death
beatty@netcom.com       _| ~-,                    Taxes
Austin, Texas           \, * }                     C++
                          \_(

Re: The Last Word on Comments (was Re: Hungarian notation)

[Darius Blasbans]

Clark L. Coleman wrote:
> 
> I have 15 years industrial software engineering experience on a variety
> of projects in a variety of software engineering environments at 4
> companies. The people who claim to be from industry and have posted
> on this subject have been really disappointing. I shudder to think that
> someone is paying them to develop code if they really think you add
> comments after the code is written.

You made a point here. Comments must be part of the code production process.

> Among the amazingly bogus statements made in this discussion was the
> declaration that any comment indicates that your language was not
> expressive enough, and hence you would ideally have no comments. This
> is surely the most ignorant statement ever made about the subject.

Please excuse me for not feeling concerned about the 'ignorant' adjective,
but I kind of disagree with you here. We try to promote an approach where
comments should be formal as far as possible, hence, executable. Assertions
(pre and post-conditions, etc...) are often understood as a quality insurance
feature, while we consider it as a way for the code to express the implicit
knowledge he (or she) has about how things are supposed to happen in
a formal, standardized, and executable way.

On the other hand, if one uses a Tree of components, using a language
with well-designed genericity, is there anything to comment, really,
about having an object:

    Data: Tree(Records);

I truly believe that higher level languages do contribute to fewer
comments. It is true that if you have a unification algorithm coded
in C++, it must be commented. It is also true that if you use
unification in a language where it is a built-in primitive (consider
Prolog, for instance), how much is there to comment ? Unless you are 
of the "i++; /* increment i */" kind of guy.

> If you have not worked on truly large projects that were proven to
> be maintainable by others after you were finished; if you have not
> worked on dozens of software engineers / hundreds of thousands of
> lines of code projects; if you don't understand what "stepwise refinement"
> really means; if you think programming consists of sketching out an
> algorithm on a sheet of paper and then coding; PLEASE do not waste
> net bandwidth replying to this message. Get an education and some real
> experience first.

I guess it would be childish to compare our experience, trying to convince
each other that "I know the real thing". Lots of big projects are developed
in a pretty foolish way. Huge projects are written with huge amounts of
documentation and comments, and still fail to deliver.

Regards,

Darius

Re: The Last Word on Comments (was Re: Hungarian notation)

[Kevin J. Weise]

Darius Blasbans <darius@phidani.be> wrote (with deletions):
>Clark L. Coleman wrote:
>> 
>> I have 15 years industrial software engineering experience on a variety
>> of projects in a variety of software engineering environments at 4
>> companies. The people who claim to be from industry and have posted
>> on this subject have been really disappointing. I shudder to think that
>> someone is paying them to develop code if they really think you add
>> comments after the code is written.
>
If you think this practice is bad, wait until you hear/read this:
I worked for a company several years ago where part of the development
environment was a PDL generator.  You got it!

   They developed the code first, then ran it through a program to
   produce the PDL to put in the design document!!  And they believed
   it was a perfectly reasonable way to do things!!

I can understand desiring to reduce the documentation effort, but to go
from B-specs to code using an undocumented process that back-filled the
design?  I can't wait to see responses to this one.

(BTW, they produced real-time systems, too, that were remarkably
rate-monotonic before I ever heard that term.)
-------------------------------------------------------------------
Kevin J. Weise                kweise@c3i-ccmail.sed.redstone.army.mil
COLSA Corporation             voice:  (205) 842-9680
Huntsville, AL

Re: The Last Word on Comments (was Re: Hungarian notation)

[Kevin D. Quitt]

On 11 Jun 1996 20:27:18 GMT, "Kevin J. Weise" 
>   They developed the code first, then ran it through a program to
>   produce the PDL to put in the design document!!  And they believed
>   it was a perfectly reasonable way to do things!!

Well, documentation should be developed first, showing the design in a
top-down manner whether or not that's how the design was done.  And the
documentation should be kept current.  I assume they had *some* documenation
to do the coding.

That being the case, it's not as strange as it may sound.  The documentation
for a project should always be up-to-date and always present the top-down
design, since that's the easiest way for somebody new to the project to get up
to speed.  Every project I finish has documentation that makes the project
look like a perfect top-down design, even though I've never managed to really
pull that off.  It's usually, start at the top, start at the bottom (low-level
code), back top, back bottom, etc., until it meets in the middle).
-- 
#include <standard_disclaimer.h>                 http://emoryi.jpl.nasa.gov/
 _
Kevin D Quitt  USA 91351-4454           96.37% of all statistics are made up
Per the FCA, this email address may not be added to any commercial mail list

Re: The Last Word on Comments (was Re: Hungarian notation)

[Kevin Cline]

In article <4pkkr6$t31@michp1.redstone.army.mil>,
Kevin J. Weise <kweise@c3i-ccmail.sed.redstone.army.mil> wrote:
 >Darius Blasbans <darius@phidani.be> wrote (with deletions):
 >>Clark L. Coleman wrote:
 >>>I shudder to think that
 >>> someone is paying them to develop code if they really think you add
 >>> comments after the code is written.
 >>
 >
 >If you think this practice is bad, wait until you hear/read this:
 >I worked for a company several years ago where part of the development
 >environment was a PDL generator.  You got it!
 >   They developed the code first, then ran it through a program to
 >   produce the PDL to put in the design document!!  And they believed
 >   it was a perfectly reasonable way to do things!!
 >
 >I can understand desiring to reduce the documentation effort, but to go
 >from B-specs to code using an undocumented process that back-filled the
 >design?  I can't wait to see responses to this one.

These practices are typically a response to documentation requirements
that result when the 2167A standard is not properly tailored.  This
can happen because the contractor doesn't know how to demonstrate that
efficient development practices are 2167A compliant, or because the
contracting officer doesn't understaind 2167A tailoring and covers his
ass by requiring every item of every DID in the document.  Probably
most of the verbage in the design documentats was useless for any practical
purpose, but supplied for some 2167A requirement.

The developers thought that writing PDL before coding was a waste of
time.  They were right.  For many projects, experienced developers can
proceed directly from OO design to API definitions (e.g. C++ class
definitions or Ada module specifications) and then to implementation.
Only DoD contractors working on cost-plus contracts have time to
write PDL, or even worry about it at all.
-- 
Kevin Cline

Re: The Last Word on Comments (was Re: Hungarian notation)

[Robert Dewar]

Darius said

"Please excuse me for not feeling concerned about the 'ignorant' adjective,
but I kind of disagree with you here. We try to promote an approach where
comments should be formal as far as possible, hence, executable. Assertions
(pre and post-conditions, etc...) are often understood as a quality insurance
feature, while we consider it as a way for the code to express the implicit
knowledge he (or she) has about how things are supposed to happen in
a formal, standardized, and executable way."

This seems quite bogus to me. The only kind of comments that can be
formalized this way are rather trivial ones that say what the code does,
and the danger of trying to formalize even these is that you end up
overspecifying and cannot describe things at the right level of
abstraction. For example, a comment that says

  "Give the error message now, in case later processing bombs, to be sure
   that the error message will be seen"

is not easily formalized. Actually this comment has two parts. The first
is the "what" [give error message now) and that is rather trivial, it may
help by abstracting what is there but it still is nly saying what the code
is doing. The rest of the comment is the WHY

The WHY is a critical part of comments, and good WHY comments are what to
me distiguishes good code. To the extent that the no-comment or lo-comment
school wants to eliminate WHY comments, they are damaging code quality in
my opinion.

Even more subtle, and difficult to formalize, but often crucial is he
the WHY NOT comment (why you didn'
t do something).

Re: The Last Word on Comments (was Re: Hungarian notation)

[James McKim]

In article <dewar.834584583@schonberg> dewar@cs.nyu.edu (Robert Dewar) writes:
>Darius said
>
>"Please excuse me for not feeling concerned about the 'ignorant' adjective,
>but I kind of disagree with you here. We try to promote an approach where
>comments should be formal as far as possible, hence, executable. Assertions
>(pre and post-conditions, etc...) are often understood as a quality insurance
>feature, while we consider it as a way for the code to express the implicit
>knowledge he (or she) has about how things are supposed to happen in
>a formal, standardized, and executable way."
>
>This seems quite bogus to me. The only kind of comments that can be
>formalized this way are rather trivial ones that say what the code does,
>and the danger of trying to formalize even these is that you end up
>overspecifying and cannot describe things at the right level of

Based on previous posts of yours I suspect you didn't think this one all
the way through. Comments that describe what the code does without giving 
away how it does it are hardly trivial or bogus. In fact these are the 
basis for information hiding and specified public interfaces of classes.
You _must_ provide these kinds of comments if you expect people to use
your class correctly without actually looking at your code. Overspecifying
(and underspecifying for that matter) is a danger whether the comments 
are compilable or not. OTOH, one of the many advantages of compilable specifications is that it is often trivial to discover when a change in
the code has introduced an error wrt the spec.
  

>abstraction. For example, a comment that says
>
>  "Give the error message now, in case later processing bombs, to be sure
>   that the error message will be seen"
>
>is not easily formalized. Actually this comment has two parts. The first
>is the "what" [give error message now) and that is rather trivial, it may
>help by abstracting what is there but it still is nly saying what the code
>is doing. The rest of the comment is the WHY
>
>The WHY is a critical part of comments, and good WHY comments are what to
>me distiguishes good code. To the extent that the no-comment or lo-comment
>school wants to eliminate WHY comments, they are damaging code quality in
>my opinion.
>
>Even more subtle, and difficult to formalize, but often crucial is he
>the WHY NOT comment (why you didn'
>t do something).

I agree that the above are important and are not easily formalized and
I didn't catch the original article, but I doubt that Darius was arguing 
that compilable pre/postconditions be the _only_ form of documentation.
I think you (Robert) are concentrating too much on documentation that
is useful only to the implementors, present and future, of the software.
Rigorous assertions are useful to both implementors _and clients_ of a
class. Continuing to think as a client, in addition to the above I would 
want documentation showing me sample uses of the class in question, yet
another form that would be difficult to formalize.

Hope this helps,
-- Jim

>


-- 

*------------------------------------------------------------------------------*
Jim McKim  (860)-548-2458     Co-editor of Eiffel Outlook 
Internet:  jcm@hgc.edu        Subscribe early and often!

Re: The Last Word on Comments (was Re: Hungarian notation)

[Robert Dewar]

"Based on previous posts of yours I suspect you didn't think this one all
the way through. Comments that describe what the code does without giving
away how it does it are hardly trivial or bogus. In fact these are the
basis for information hiding and specified public interfaces of classes."

I certainly agree with that, when I said "what the code does", I was
talking about literal description, but in an earlier post I noted thta
comments which describe the what *abstracted to a higher level* are 
indeed valuable, and can indeed be formalized to a limited extent.

Still only to a limited extent ....

What does this code do?
It examines the data and outputs nice error messages for any inconsistencies

This is a *what* type description, but certainly not one that can be
formalized in any useful way.

Re: The Last Word on Comments (was Re: Hungarian notation)

[Darius Blasbans]

Clark L. Coleman wrote:
> 
> I have 15 years industrial software engineering experience on a variety
> of projects in a variety of software engineering environments at 4
> companies. The people who claim to be from industry and have posted
> on this subject have been really disappointing. I shudder to think that
> someone is paying them to develop code if they really think you add
> comments after the code is written.

You made a point here. Comments must be part of the code production process.

> Among the amazingly bogus statements made in this discussion was the
> declaration that any comment indicates that your language was not
> expressive enough, and hence you would ideally have no comments. This
> is surely the most ignorant statement ever made about the subject.

Please excuse me for not feeling concerned about the 'ignorant' adjective,
but I kind of disagree with you here. We try to promote an approach where
comments should be formal as far as possible, hence, executable. Assertions
(pre and post-conditions, etc...) are often understood as a quality insurance
feature, while we consider it as a way for the code to express the implicit
knowledge he (or she) has about how things are supposed to happen in
a formal, standardized, and executable way.

On the other hand, if one uses a Tree of components, using a language
with well-designed genericity, is there anything to comment, really,
about having an object:

    Data: Tree(Records);

I truly believe that higher level languages do contribute to fewer
comments. It is true that if you have a unification algorithm coded
in C++, it must be commented. It is also true that if you use
unification in a language where it is a built-in primitive (consider
Prolog, for instance), how much is there to comment ? Unless you are 
of the "i++; /* increment i */" kind of guy.

> If you have not worked on truly large projects that were proven to
> be maintainable by others after you were finished; if you have not
> worked on dozens of software engineers / hundreds of thousands of
> lines of code projects; if you don't understand what "stepwise refinement"
> really means; if you think programming consists of sketching out an
> algorithm on a sheet of paper and then coding; PLEASE do not waste
> net bandwidth replying to this message. Get an education and some real
> experience first.

I guess it would be childish to compare our experience, trying to convince
each other that "I know the real thing". Lots of big projects are developed
in a pretty foolish way. Huge projects are written with huge amounts of
documentation and comments, and still fail to deliver.

Regards,

Darius

Re: The Last Word on Comments (was Re: Hungarian notation)

[Darius Blasbans]

Clark L. Coleman wrote:
> 
> I have 15 years industrial software engineering experience on a variety
> of projects in a variety of software engineering environments at 4
> companies. The people who claim to be from industry and have posted
> on this subject have been really disappointing. I shudder to think that
> someone is paying them to develop code if they really think you add
> comments after the code is written.

You made a point here. Comments must be part of the code production process.

> Among the amazingly bogus statements made in this discussion was the
> declaration that any comment indicates that your language was not
> expressive enough, and hence you would ideally have no comments. This
> is surely the most ignorant statement ever made about the subject.

Please excuse me for not feeling concerned about the 'ignorant' adjective,
but I kind of disagree with you here. We try to promote an approach where
comments should be formal as far as possible, hence, executable. Assertions
(pre and post-conditions, etc...) are often understood as a quality insurance
feature, while we consider it as a way for the code to express the implicit
knowledge he (or she) has about how things are supposed to happen in
a formal, standardized, and executable way.

On the other hand, if one uses a Tree of components, using a language
with well-designed genericity, is there anything to comment, really,
about having an object:

    Data: Tree(Records);

I truly believe that higher level languages do contribute to fewer
comments. It is true that if you have a unification algorithm coded
in C++, it must be commented. It is also true that if you use
unification in a language where it is a built-in primitive (consider
Prolog, for instance), how much is there to comment ? Unless you are 
of the "i++; /* increment i */" kind of guy.

> If you have not worked on truly large projects that were proven to
> be maintainable by others after you were finished; if you have not
> worked on dozens of software engineers / hundreds of thousands of
> lines of code projects; if you don't understand what "stepwise refinement"
> really means; if you think programming consists of sketching out an
> algorithm on a sheet of paper and then coding; PLEASE do not waste
> net bandwidth replying to this message. Get an education and some real
> experience first.

I guess it would be childish to compare our experience, trying to convince
each other that "I know the real thing". Lots of big projects are developed
in a pretty foolish way. Huge projects are written with huge amounts of
documentation and comments, and still fail to deliver.

Regards,

Darius

Re: The Last Word on Comments (was Re: Hungarian notation)

[Darius Blasbans]

Clark L. Coleman wrote:
> 
> I have 15 years industrial software engineering experience on a variety
> of projects in a variety of software engineering environments at 4
> companies. The people who claim to be from industry and have posted
> on this subject have been really disappointing. I shudder to think that
> someone is paying them to develop code if they really think you add
> comments after the code is written.

You made a point here. Comments must be part of the code production process.

> Among the amazingly bogus statements made in this discussion was the
> declaration that any comment indicates that your language was not
> expressive enough, and hence you would ideally have no comments. This
> is surely the most ignorant statement ever made about the subject.

Please excuse me for not feeling concerned about the 'ignorant' adjective,
but I kind of disagree with you here. We try to promote an approach where
comments should be formal as far as possible, hence, executable. Assertions
(pre and post-conditions, etc...) are often understood as a quality insurance
feature, while we consider it as a way for the code to express the implicit
knowledge he (or she) has about how things are supposed to happen in
a formal, standardized, and executable way.

On the other hand, if one uses a Tree of components, using a language
with well-designed genericity, is there anything to comment, really,
about having an object:

    Data: Tree(Records);

I truly believe that higher level languages do contribute to fewer
comments. It is true that if you have a unification algorithm coded
in C++, it must be commented. It is also true that if you use
unification in a language where it is a built-in primitive (consider
Prolog, for instance), how much is there to comment ? Unless you are 
of the "i++; /* increment i */" kind of guy.

> If you have not worked on truly large projects that were proven to
> be maintainable by others after you were finished; if you have not
> worked on dozens of software engineers / hundreds of thousands of
> lines of code projects; if you don't understand what "stepwise refinement"
> really means; if you think programming consists of sketching out an
> algorithm on a sheet of paper and then coding; PLEASE do not waste
> net bandwidth replying to this message. Get an education and some real
> experience first.

I guess it would be childish to compare our experience, trying to convince
each other that "I know the real thing". Lots of big projects are developed
in a pretty foolish way. Huge projects are written with huge amounts of
documentation and comments, and still fail to deliver.

Regards,

Darius

Re: The Last Word on Comments (was Re: Hungarian notation)

[Darius Blasbans]

Clark L. Coleman wrote:
> 
> I have 15 years industrial software engineering experience on a variety
> of projects in a variety of software engineering environments at 4
> companies. The people who claim to be from industry and have posted
> on this subject have been really disappointing. I shudder to think that
> someone is paying them to develop code if they really think you add
> comments after the code is written.

You made a point here. Comments must be part of the code production process.

> Among the amazingly bogus statements made in this discussion was the
> declaration that any comment indicates that your language was not
> expressive enough, and hence you would ideally have no comments. This
> is surely the most ignorant statement ever made about the subject.

Please excuse me for not feeling concerned about the 'ignorant' adjective,
but I kind of disagree with you here. We try to promote an approach where
comments should be formal as far as possible, hence, executable. Assertions
(pre and post-conditions, etc...) are often understood as a quality insurance
feature, while we consider it as a way for the code to express the implicit
knowledge he (or she) has about how things are supposed to happen in
a formal, standardized, and executable way.

On the other hand, if one uses a Tree of components, using a language
with well-designed genericity, is there anything to comment, really,
about having an object:

    Data: Tree(Records);

I truly believe that higher level languages do contribute to fewer
comments. It is true that if you have a unification algorithm coded
in C++, it must be commented. It is also true that if you use
unification in a language where it is a built-in primitive (consider
Prolog, for instance), how much is there to comment ? Unless you are 
of the "i++; /* increment i */" kind of guy.

> If you have not worked on truly large projects that were proven to
> be maintainable by others after you were finished; if you have not
> worked on dozens of software engineers / hundreds of thousands of
> lines of code projects; if you don't understand what "stepwise refinement"
> really means; if you think programming consists of sketching out an
> algorithm on a sheet of paper and then coding; PLEASE do not waste
> net bandwidth replying to this message. Get an education and some real
> experience first.

I guess it would be childish to compare our experience, trying to convince
each other that "I know the real thing". Lots of big projects are developed
in a pretty foolish way. Huge projects are written with huge amounts of
documentation and comments, and still fail to deliver.

Regards,

Darius

Re: Hungarian notation

[Ralph Silverman]

Bob Rodgers (rsrodger@wam.umd.edu) wrote:
: dewar@cs.nyu.edu (Robert Dewar) wrote:
: >Well, I guess they just don't want to comment the code and don't come to ask
: >you question anymore.  I'm a student in CS, and I know what the students feel.
: > When the project is dued soon and don't get the program works, do you still
: >have time to comment to code?"

: Yes.  Yes, you certainly do.  In fact, if you haven't been commenting
: all along, that's probably why you're pushing the deadline and the
: project doesn't work yet.

: The time to start programming right is *now*, not later.  I laugh when
: I see or hear a CS teacher who says they get caught by the assignment
: = in conditional expressions, since no modern compiler lacks the
: ability to flag this as an error (or the old constant-first trick,
: e.g., "if(3 = x)" will **always** error)  if you decide to read one or
: two pages of documentation.

: >On the contrary, my students know that working code is useless to hand in
: >if it is not commented, so they *have* to comment the code. In fact a
: >well-commented and well-designed but not quite working assignment gets
: >much more credit than a fully working program which is poorly designed,
: >or has incomplete or incomprehensible comments. 

: One of the problems in CS is the focus on "execution" correctness
: instead of overall correctness.  It's a lot easier to grade (it either
: works, or it doesn't), but it doesn't really address student
: difficulties (especially with pointers, which kill first year student
: projects all the time without them even knowing how to identify it as
: anything but "it's acting weird, time to reboot"), nor grade on the
: quality of the code.

: One thing I remember, and will always remember, is a statement from a
: teacher: "If you have a bug, you have an error."  I was quite frankly
: surprised at how many students didn't realize this -- instead, they
: tried to solve project problems with various degrees of mojo --
: rebooting, renaming their data files, changing where things are in a
: file, compiling with and without debug code.  Some beleagered students
: will actually print out their project and re-type the "problem
: sections" -- accidently fixing errors, or making them less apparent
: (i.e., serious pointer problems that, by happenstance, make the
: program crash sooner or later, or not at all, even though they haven't
: actually moved).

: CS education is in a sorry state when the only criteria to pass a
: class are the ability to memorize the string function examples and get
: a project working, even if it's spaghetti.


--
**********begin r.s. response***********

	why not major in
		hegelian metaphysics
	or
		creative writing (modern poetry)
	?
	generally there is no 'compiler' or assembler
	and
	nothing to do (in these)
	but handhold with teachers and other students!

	is not one of the great things about programming
	that it has the
		objective component
	of making thing which
		ACTUALLY WORK!!!
		^^^^^^^^^^^^^^^^

	reasonably,
	working,  compilable (and/or assemblable)
	code
	and
	comments
	are not on the same level.

	computer programmers,  i guess,
		PROGRAM COMPUTERS
		^^^^^^^^^^^^^^^^^
	yes
	?

**********end r.s response**************
Ralph Silverman
z007400b@bcfreenet.seflin.lib.fl.us

Re: Hungarian notation

[David Hopkins]

Ralph Silverman wrote:

> **********begin r.s. response***********
> 
>         why not major in
>                 hegelian metaphysics
>         or
>                 creative writing (modern poetry)
>         ?
>         generally there is no 'compiler' or assembler
>         and
>         nothing to do (in these)
>         but handhold with teachers and other students!
> 
>         is not one of the great things about programming
>         that it has the
>                 objective component
>         of making thing which
>                 ACTUALLY WORK!!!
>                 ^^^^^^^^^^^^^^^^
> 
>         reasonably,
>         working,  compilable (and/or assemblable)
>         code
>         and
>         comments
>         are not on the same level.
> 
>         computer programmers,  i guess,
>                 PROGRAM COMPUTERS
>                 ^^^^^^^^^^^^^^^^^
>         yes
>         ?
> 
> **********end r.s response**************
> Ralph Silverman
> z007400b@bcfreenet.seflin.lib.fl.us

What's the deal with Ralph's responses?  Kind of makes it hard to read, 
you know?

Re: Hungarian notation

[Richard A. O'Keefe]

z007400b@bcfreenet.seflin.lib.fl.us (Ralph Silverman) writes:
>	why not major in
>		hegelian metaphysics
>	or
>		creative writing (modern poetry)

For many students, the literally correct answer is "because a major in
creative writing is not a meal ticket, but a major in computing is."

Dijkstra once wrote that the two prerequisites for becoming a good
programmer were
    - a propensity (my word, not his) for mathematics
    - mastery of ones native language.

I am not the only person in this department who wishes that more of our
students had attained at least "advanced apprentice" English skills.  A
good creative writing course might work wonders, especially one of those
ones where you are taught how to _rewrite_.

>	is not one of the great things about programming
>	that it has the
>		objective component
>	of making thing which
>		ACTUALLY WORK!!!

There is no branch of technology in which technical writing skills are
not important.  Once you have built something, you have to tell other
people how to operate and maintain it.  Making something that actually
works is not the *end* of computing, it's the *beginning*.

>	computer programmers,  i guess,
>		PROGRAM COMPUTERS

This is, alas, painfully true.  There are too perishing many programmers.
What we need is more software engineers:  people who can not only produce
code that works but explain it so well that it keeps *on* working as the
necessary adaptive changes are made.  Show me someone who things that
computing is all about programming, and I'll show you someone whose test
plans aren't nearly good enough.

-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

Re: Hungarian notation

[Steve Willer]

ok@goanna.cs.rmit.edu.au (Richard A. O'Keefe) wrote:

>I am not the only person in this department who wishes that more of our
>students had attained at least "advanced apprentice" English skills.  A
>good creative writing course might work wonders, especially one of those
>ones where you are taught how to _rewrite_.

My own experience with some of my co-workers is that typing skills are
very important as well. If the programmer has to hunt-and-peck at 20
words a minute, they would be inclined to write minimal comments, log
messages, etc., using abbreviations that nobody except themselves can
understand. Plus, it promotes the naming of variables like "var",
"evnt", etc.

>This is, alas, painfully true.  There are too perishing many programmers.
>What we need is more software engineers:  people who can not only produce
>code that works but explain it so well that it keeps *on* working as the
>necessary adaptive changes are made.  Show me someone who things that
>computing is all about programming, and I'll show you someone whose test
>plans aren't nearly good enough.

And don't forget designs.

Re: Hungarian notation

[Michael Furman]

In article <31b83962.670331135@sqarc.sq.com>, willer@carolian.com says...
> [....]
>
>My own experience with some of my co-workers is that typing skills are
>very important as well. If the programmer has to hunt-and-peck at 20
>words a minute, they would be inclined to write minimal comments, log
>messages, etc., using abbreviations that nobody except themselves can
>understand. Plus, it promotes the naming of variables like "var",
>"evnt", etc.

   Interesting that my experiance is exectly opposite. Almost all programmer
I worked with or watched their work, who were typing fast produced poor
code (may be with comments, but often redundant or meaningless). I believe
they (usually) just don't have enough time to think.
   I personally sometimes write comments just to think one more time trough
just written code (or code I'm going to write). It helps find bugs (even
in design) and sometimes find better solution. 

---------------------------------------------------------------
Michael Furman,                       (603)893-1109
Geophysical Survey Systems, Inc.  fax:(603)889-3984
13 Klein Drive - P.O. Box 97          engr@gssi.mv.com 
North Salem, NH 03073-0097            71543.1334@compuserve.com
---------------------------------------------------------------

Re: Hungarian notation

[Warren Young]

ENGR@GSSI.MV.COM (Michael Furman) wrote:

>>My own experience with some of my co-workers is that typing skills are
>>very important as well. If the programmer has to hunt-and-peck at 20
>>words a minute, they would be inclined to write minimal comments, log
>>messages, etc., using abbreviations that nobody except themselves can
>>understand. Plus, it promotes the naming of variables like "var",
>>"evnt", etc.
>
>   Interesting that my experiance is exectly opposite. Almost all programmer
>I worked with or watched their work, who were typing fast produced poor
>code (may be with comments, but often redundant or meaningless). I believe
>they (usually) just don't have enough time to think.

I dunno, I think there's truth in both statements.  From my own
experience, my code has become more verbose over the years as my
typing speed has increased.  Some of this is just that I know better
now, but some of it is that it's much less painful to be verbose.  

On the other hand, I know a guy at work who hunts and pecks (often
with only one hand!) and he's the most verbose coder I know.  I think
he's a bit of an exception, though, because he doesn't write much
code, so he probably just wants to make his reimmersion time as low as
possible.  For what it's worth, he also prefers writing everything in
a single module, so he always knows where everything's at.  B-)

I think that there are two basic types of programmers, as far as this
goes, and that people move from the first to the second with training
or experience.  The first group is those who think that getting the
program done as fast as possible is a function of the amount of code
written per hour.  The second is those who know all of the steps
necessary to turn out a good, solid product.  Their current "type" and
their typing speed together influence the programmer's documentation
skills.  So, for your approval, here are some quick summaries of the
type combinations:

Slow typists who want to turn out a lot of code are terse.  I think a
lot of newbies fall into this category.

Slow typists who know how to document well try to write the code
correctly the first time.  (They know they are slow, so they take the
time to think things through before coding, so they don't have to
re-write as much.)  Programmers originally trained as engineers
probably fall into this category at first; they're not good typists
because they don't have the practice, but they know how to write good
supporting documentation because that's part of an engineer's
training.

Fast typists who don't know how to document well (or don't care)
simply turn out many, many lines of rubbish.  They may get the job
done, though, because their speed lets them re-write several times in
the time it takes a slow programmer to do it once.  Again, this
exemplifies many newbies, except that these ones can type.

Fast typists who know how to document well force themselves to take
the time to think things over as they go along.  Comments help because
they force a change of pace, and they force a re-think of what's going
on.  Hungarian Notation probably helps, too, because it can act as a
governor on the typist's speed, since they often have to take the time
to think the prefixes through before continuing.

>   I personally sometimes write comments just to think one more time trough
>just written code (or code I'm going to write). It helps find bugs (even
>in design) and sometimes find better solution. 

Ditto, wholeheartedly.  I think this works because a good commenter is
trying to explain the following bit of code (or mention what isn't
obvious).  In doing so, you are casting yourself in the role of a
teacher, probably to someone who knows less about this bit of code
than you do.  The result is that it forces you to rethink the code.  I
find that if I have to use a 10-line comment to explain four lines of
code, one of the two (the code or the comment) is probably too
complex.  I usually re-write one or the other, and the whole is
improved as a result.

As for your "design" comment, I also agree.  Comments should be one
level above the code -- the design level, in other words.  (By the by,
this is why the people who argue that the code alone is sufficient
documentation are wrong, IMO.)  So, you're re-doing the design as you
write the code that implements that design.  If you can write the code
and comments easily, the design is probably correct.  If either one
becomes a problem, it's a hint that the design may be flawed.

I find that comments are really good at throwing light on over-complex
intercommunications and interdependencies.  The comments document
what's going on at the level above the actual code, which includes the
intercommunications.  Well, if you find yourself rambling on in a
comment about how this object communicates with the others it needs to
communicate with to do its work and about the special rules involved,
it's probably a clue that something's too complex.

All of that in a nutshell: Comments reflect something of the code and
of the coder.  You can learn to use those comments not only for
documentation, but as a potential problem indicator.

= Warren -- http://www.cyberport.com/~tangent

Re: Hungarian notation (an aside)

[Bob Lang 3P21 x3172]

In article <4p6mor$qbb@nntp.seflin.lib.fl.us>, z007400b@bcfreenet.seflin.lib.fl.us (Ralph Silverman) writes:

> **********begin r.s. response***********
> 
> 	why not major in
> 		hegelian metaphysics
> 	or
> 		creative writing (modern poetry)
> 	?
> 	generally there is no 'compiler' or assembler
> 	and
> 	nothing to do (in these)
> 	but handhold with teachers and other students!
> 
> 	is not one of the great things about programming
> 	that it has the
> 		objective component
> 	of making thing which
> 		ACTUALLY WORK!!!
> 		^^^^^^^^^^^^^^^^
> 
> 	reasonably,
> 	working,  compilable (and/or assemblable)
> 	code
> 	and
> 	comments
> 	are not on the same level.
> 
> 	computer programmers,  i guess,
> 		PROGRAM COMPUTERS
> 		^^^^^^^^^^^^^^^^^
> 	yes
> 	?
> 
> **********end r.s response**************

	i (bet) 
	  [you/really} 
	  {like] :
		e e cummings

Bob

Re: Hungarian notation

[Sam Hunting]

Yang:

>: >On the contrary, my students know that working code is useless to hand in
>: >if it is not commented, so they *have* to comment the code. In fact a
>: >well-commented and well-designed but not quite working assignment gets
>: >much more credit than a fully working program which is poorly designed,
>: >or has incomplete or incomprehensible comments. 

Yin:

>	why not major in
>		hegelian metaphysics
>	or
>		creative writing (modern poetry)
>	?

Ah, the age old conflict between the rhetorical and philosophical world! 
Castiglione called the ability to hold these two antithetical worldviews 
in mind simultaneously "sprezzatura." 

Both "sides" are right, of course....
-- 
<!-- 
  "To imagine a language is to imagine a form 
   of life."                   - Wittgenstein,
                 Philosophical Investigations

I wish it was "The Last Word on Comments (was Re: Hungarian notation)"

[Blair MacIntyre]

>>>>> On Tue, 11 Jun 1996 18:55:08 +0200, Darius Blasbans
>>>>> <darius@phidani.be> said:

[the same damn thing 5 time, that has no relevance to half the groups it was
 crossposted to]

While I'm sure some people care about this Thread-that-refuses-to-die,
could you people PLEASE EDIT THE NEWSGROUP LINE?

Nobody in half these groups really gives an <*explitive*> about this topic.
Actually, I'm not sure which of these groups is appropriate, but I
sure know it isn't comp.lang.modula3.

Thanks.

ObInsult (since half a dozen nice requests haven't yielded any results):
  I suppose it won't happen though.  If you still program is C or C++,
  you probably aren't capable of editing a newsgroup line.

  And your mother dresses you funny.  So there.

-- 
Blair MacIntyre (bm@cs.columbia.edu), Graduate Student (Graphics and UI Lab)

smail: Dept. of Computer Science, 450 Computer Science Building, 500 W 120 St.
       Columbia University, New York, NY 10027

Re: Hungarian notation

[Robert Dewar]

Peter Moylan wrote:

.Richard A. O'Keefe (ok@goanna.cs.rmit.EDU.AU) wrote:
.>nreitzel@lonestar.jpl.utsa.edu (Norman L. Reitzel   ) writes:
.>>As for serious code, I've ported million line projects for a telephone
.>>company, and managed projects that produced twice that.  The key to
.>>maintainability is defensive programming, and ADEQUATE BLOCK COMMENTS.
.>>Any chunk of code that does not contain info about what it does and how
.>>it does it is an error waiting to happen.  The rude concept of
.>>"self-documenting" code belongs in an ivory tower with those who teach,
.>>not in the trenches with those of us who DO.
.
.>Those of us who teach struggle hard to persuade students to write
.>good comments.
.
.I don't know where this myth comes from.  In my 20+ years in
.academia, I have NEVER met a software teacher who considered
.uncommented code to be acceptable.  Practically everyone tries
.to get across the message "write the comments first, and then
.the code".

In fact the anti-comment attitude comes from the trenches rather than from
the ivory tower. The main argument seems to be that since no one can ever
manage to maintain comments properly, it is better to have no comments, or
at least to minimize comments. I strongly disagree, and feel that it is
better still to keep the comments up to date. A bad comment is a bug, as
serious as any other latent bug in the "real" code, and programmers have
to start thinking that way.

Yes of course it is hard to keep comments up to date -- there are many
hard things about programming, this is one of them.

To see the anti-comment view, look at section 3.3 of AQ&S (one of the few
sections of this document that I am not fond of). It starts by saying

  "Comments in source text are a controversial issue"  (!)

and then goes on to present what supposedly is a balanced discussion on this
issue that to my taste is far too anti-comment. Some excerpts:

  "There are argments both for and against the view that comments
   enhance readability"

  "Comments should be minimized"

  "source text should .. so that little additional commentary is needed"

There is nothing exactly *wrong* with any of these statements, but the
general tone adds up to me to be far too anti-comment.

As Peter says, most teachers stress comments. I certainly give zero to any
assignment that is uncommented, and take marks off for incompetent, incorrect
or annoyingly useless ("increment I") comments.

In practice many programmers are incapable of writing coherent English, so
they have no chance in any case of writing useful comments, and many other
programmers are lazy and don't feel like commenting code. Maintenance
programmers are often still more lazy and try to change the minimum number
of characters to make a problem go away, and of course this does not include
changing comments.

To me good comments are essential, the code can only tell you what it does
and how at a level of abstraction matching the code. Good comments tell you:

   a) what the code is doing at a higher level of abstraction
   b) why you did what you did
   c) why you didn't do something else

obviously code cannot be self-documenting in these three aspects.

Of course I agree that incorrect or inconsistent or out-of-date comments
are a menace, but that's an argument for making sure the comments are
correct, consistent and up-to-date, not for eliminating them!

Incidentally, I also follow Peter's rule of never helping with uncommented
code, and in fact if students show me uncommented code, I take marks off
the assignment no matter WHAT is eventually handed in, since I insist
that coments must be written as part of the process of coding, not as an
after-thought. In practice, this works very well, since I use email to
give continuous feedback to students on early versions of their assignments,
and they find this feedback valuable enough to be worth the nuisance of
commenting their code!

Re: Hungarian notation

[Steve Willer]

dewar@cs.nyu.edu (Robert Dewar) wrote:

>In fact the anti-comment attitude comes from the trenches rather than from
>the ivory tower. The main argument seems to be that since no one can ever
>manage to maintain comments properly, it is better to have no comments, or
>at least to minimize comments. 

As with everything, comments can hurt or they can help. If you require
the developer to sprinkle comments all over their code, they will almost
certainly get out of date.

I prefer to concentrate on writing code that's as clear and
self-documenting as possible, inserting comments in places where it is
necessary to give the "big picture" of what I'm doing. I've found it
counterproductive to create comments like this, for example:

Bar(vector<Foo> &vFoo) {
   // for each Foo...
   for_iter(vFoo, FooIterator) {
      // run some calculations on it
      DoSomeStuff(*iter);
   }
}

(Please excuse my for_iter macro; I'm very proud of my new creation and
I like to use it whenever possible)

The above code is an example of the "write comments that indicate the
structure of your code" form of commenting that I played around with for
a while. I found it unwieldy. I also decided that if your code is so
complicated that you have to comment _every step_, then you need to
rethink your design.

But as I noted earlier, there are times when comments are very good for
giving context to an unfortunate hack you had to pull together, or a
particularly complicated algorithm. I tend to write those in "essay"
style, sometimes making them 5-9 lines of comments.

I also write up comments to subdivide logical sections of medium-length
functions (I completely disallow longer functions)...perhaps something
like:

bool Go() {
   // initialize the internal View
   ...

   // generate the output
   ...

   // cleanup
   ...
}

...but that's as far as I go. Is that less than what you like, or is it
what you're talking about?

>As Peter says, most teachers stress comments. I certainly give zero to any
>assignment that is uncommented, and take marks off for incompetent, incorrect
>or annoyingly useless ("increment I") comments.

I wish teachers would also stress the need for writing code that's as
self-documenting as possible. If it's possible to make code very clear
without comments, I feel that's much more valuable than adding comments.

>In practice many programmers are incapable of writing coherent English, so
>they have no chance in any case of writing useful comments, and many other
>programmers are lazy and don't feel like commenting code. 

Lots of those. :-)

>Maintenance
>programmers are often still more lazy and try to change the minimum number
>of characters to make a problem go away, and of course this does not include
>changing comments.

Part of the reason I try to keep it at a minimum.

Re: Hungarian notation

[Richard A. O'Keefe]

willer@carolian.com (Steve Willer) writes:

>I wish teachers would also stress the need for writing code that's as
>self-documenting as possible. If it's possible to make code very clear
>without comments, I feel that's much more valuable than adding comments.

I do.  In the past I've spent a lot of time preaching the
Gospel about identifiers:
	an identifier's name cannot tell you the *whole* truth
	about what it means,
	but it should tell you nothing *but* the truth,
	and it should do so clearly and simply.

And then students go and do things like
	struct rectypes {
			PersonList *Plist;
			MatingList *Mlist;
	};
(pasted from an actual assignment in another window).
Do I need to point out that the "PersonList" type is not a list?

This is one of those things that you just don't appreciate until
you try to read someone else's code.

Does anyone know where I can find a non-trivial body of *well-written*
C or C++ code?  I've looked all over, and the only stuff I found was
pre-ANSI.

-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

Re: Hungarian notation

[Kevin Cline]

In article <4oeh0n$o6g@goanna.cs.rmit.EDU.AU>,
Richard A. O'Keefe <ok@goanna.cs.rmit.EDU.AU> wrote:
>Does anyone know where I can find a non-trivial body of *well-written*
>C or C++ code?  

I found the GNU-Emacs C code to be pretty good -- an experienced 
C programmer can read it, understand it, and modify it without 
undue effort.  It probably won't satisfy you, though.

For C++ code, take a look at Doug Schmidt's ACE wrappers.  You can find
them via http://www.cs.wustl.edu/~schmidt/

-- 
Kevin Cline

Re: Hungarian notation

[Kevin Cline]

In article <dewar.832851446@schonberg>, Robert Dewar <dewar@cs.nyu.edu> wrote:
 >.I don't know where this myth comes from.  In my 20+ years in
 >.academia, I have NEVER met a software teacher who considered
 >.uncommented code to be acceptable.  Practically everyone tries
 >.to get across the message "write the comments first, and then
 >.the code".

How much time do you spend showing your students how to 
write useful comments, or demonstrating good coding style?

Is Kernighan & Plaugher's "The Elements of Programming Style" 
a required or suggested text at NYU?

This is a subject that seems to be largely ignored in undergraduate
curricula.  The developers that do know how to comment seem to have
learned by example.

 >In fact the anti-comment attitude comes from the trenches rather than from
 >the ivory tower. 
 >The main argument seems to be that since no one can ever
 >manage to maintain comments properly, it is better to have no comments, or
 >at least to minimize comments. I strongly disagree, and feel that it is
 >better still to keep the comments up to date. A bad comment is a bug, as
 >serious as any other latent bug in the "real" code, and programmers have
 >to start thinking that way.

Comments should rarely require maintainence.  Largely they should be
limited to describing a class and it's relationship to other classes,
or describing the inputs, outputs, preconditions and postconditions
for an entire method.  Few methods should be so complex that they
require additional comments describing the method implementation.

 >Yes of course it is hard to keep comments up to date -- there are many
 >hard things about programming, this is one of them.
 >
 >To see the anti-comment view, look at section 3.3 of AQ&S (one of the few
 >sections of this document that I am not fond of). It starts by saying
 >
 >  "Comments in source text are a controversial issue"  (!)
 >
 >and then goes on to present what supposedly is a balanced discussion on this
 >issue that to my taste is far too anti-comment. Some excerpts:
 >
 >  "There are argments both for and against the view that comments
 >   enhance readability"
 >
 >  "Comments should be minimized"
 >
 >  "source text should .. so that little additional commentary is needed"
 >
 >There is nothing exactly *wrong* with any of these statements, but the
 >general tone adds up to me to be far too anti-comment.

I really liked this section.  I thought it was very important to
counter the typical methodologies of 2167A DoD software projects, which
had a tendency to have rules like "one comment for every five lines of code".
Maybe Mr. Dewar has been fortunate enough to have never worked on a software
developed using DoD 2167A methodology.

>As Peter says, most teachers stress comments. I certainly give zero to any
>assignment that is uncommented, and take marks off for incompetent, incorrect
>or annoyingly useless ("increment I") comments.

Most teachers tell students to comment.  Few seem interested in telling
students how to write useful comments.  

 >To me good comments are essential, the code can only tell you what it does
 >and how at a level of abstraction matching the code. Good comments tell you:
 >
 >   a) what the code is doing at a higher level of abstraction
 >   b) why you did what you did
 >   c) why you didn't do something else
 >
 >obviously code cannot be self-documenting in these three aspects.

Agreed!!  But these comments seldom require maintainence.  Most
maintainence involves either fixing bugs in old code, or adding
new features to old code, presumably by adding new methods.
These activities should seldom require changing existing comments.

Less frequently, implementation decisions will change, and these
changes should be documented.

 >Of course I agree that incorrect or inconsistent or out-of-date comments
 >are a menace, but that's an argument for making sure the comments are
 >correct, consistent and up-to-date, not for eliminating them!
 >
 >Incidentally, I also follow Peter's rule of never helping with uncommented
 >code, and in fact if students show me uncommented code, I take marks off
 >the assignment no matter WHAT is eventually handed in, since I insist
 >that coments must be written as part of the process of coding, not as an
 >after-thought. In practice, this works very well, since I use email to
 >give continuous feedback to students on early versions of their assignments,
 >and they find this feedback valuable enough to be worth the nuisance of
 >commenting their code!

That's good.  Presumably you are giving them feedback on their commenting
and coding style as well.  Your students should be well-prepared.
-- 
Kevin Cline

Re: Hungarian notation

[Steve Willer]

kcline@sun132.spd.dsccc.com (Kevin Cline) wrote:

>This is a subject that seems to be largely ignored in undergraduate
>curricula.  The developers that do know how to comment seem to have
>learned by example.

This is a very interesting point, and one that my own experience as a
former student supports. Although my teachers did require that the code
be commented, they never made a reasonable attempt at teaching us what
kind of comments should be created, why they're important, caveats, etc.

I've had a continuing discussion via e-mail on this topic, and I thought
I wrote a reasonably good letter today that perhaps gets into more
specifics. I'll reproduce it here:

---------------------------------------------------------------------
>Note that everyone agrees that silly comments that just repeat what the
>code is doing are useless, but on the other hand, I find the idea of
>self-documenting code to be largely bogus. The most code can tell you
>is what it does and how it does it (true -- much poorly written code
>can't even tell you that).

Well, let's say for the sake of argument that it _is_ possible to have
fairly good self-documenting code. Would you agree that self-documenting
code would be more valuable, from a maintenance perspective, than any
comments within the functions?

You see, I believe strongly that it _is_ possible to make code clear
without resorting to side commentary. So I strive to achieve this
whenever possible, and I find that a good notation system helps
tremendously.

Let me give a quick analogy. If you're watching a movie and you just
don't understand what's going on, if you had a choice between someone
whispering explanations in your ear and having the movie make sense in
the first place, you would probably choose the latter, right? I find
that comments sprinkled throughout the code break the "flow" and
therefore damage the ability of the maintainer to understand the way the
code works without having to mentally step through every line of code.

>BUT! it can't tell you the why, and even less the why not (why you did not
>do something else). Furthermore, properly written comments are at a level
>of abstraction that is definitely above the level of the code, and this
>can make it far easier to follow the intent and shape of code without
>having to read the code itself (which is at a more detailed level, and 
>therefore takes more effort to read).

Part of the problem is that there are so many different types of
comments, it's difficult to have a good discussion about them without
recognizing the different types.

In particular, there are:

1. design documentation (I consider this to be related to comments)
2. "headers" at the top of functions, indicating what the function does,
   what the parameters mean, etc.
3. "procedural" comments, which are of the "literate programming"
   variety, like the example I gave earlier

[Note: this point refers to comments that are created to show program
structure before the code is written, which is suggested in at least one
book that I've read. An example might be:
   // for every node
      // tell the node to output its iteration
   // tell the user that we're done
]

4. "low-level overview" comments, which indicate what is going to
   be done in a 5-15 line segment. They can also serve to separate
   a function into multiple higher-level segments.
5. "hack" comments, which document a weird hack or bizarre form of
   algorithm that you are employing

Now, your comment about the useless comments seems to be about the "bad"
form of #3. My own personal experience is that I don't get much use out
of #3 at all, despite the fact that a number of books seem to recommend
this practice. My comment at the top of this letter is in fact about #3
specifically.

I personally feel that #1 and #2 are absolutely required for any
software that will be maintained by a different person or a few months
down the road (i.e. all software). I also feel that #5 is very
important, partly so maintainers can understand why the hack was put in,
but also perhaps more importantly to be sure that they don't undo the
hack (probably every developer has at least once looked in disgust at a
hack and "cleaned it up," only to discover later that there was a good
reason for it being there).

Now, #4, I tend to feel is optional. I try to limit my use of #4 to
places where the functions are long or complicated, but since I'm a C++
programmer, one of the design principles I try to live by is "write
simple functions". Consequently, #4 isn't needed very much in my code.
This is an example where I feel it's much more important to concentrate
on design principles than commenting principles.

I guess my biggest objection to the "comments are God" type of attitude
I see sometimes is that there are more important things to be done, like
fixing a bad design. I don't want to see comments being used to cover up
a bad design or bad code.

Hungarian notation: the thread of choice for consummate boors

[The Right Reverend Colin James III]

[groups trimmed to exclude those listed below]

Several articles have already politely requested that the thread "Hungarian
notation" be excluded from:

comp.lang.eiffel
comp.lang.modula2
comp.lang.modula3

What is remarkable is how selfish (and disrespectful of others) the
propagators of the thread are in ignoring such requests.

Such notorious posters as Robert Dewar, NYU academic and Ada compiler
vendor, among others, rank right up there in forcing their irrelevant and
queer opinions on more than three usenet groups, namely seven, which is the
height of rudeness and bad manners.

What follows is that the propagators are in fact consummate boors, and are
best advised to "get a life" and to stop wasting everyone's time, including
their own.

Re: Hungarian notation: the thread of choice for consummate boors

[Ken Nicolson]

cjames@cec-services.com (The Right Reverend Colin James III) wrote:

[from header]
>From: cjames@cec-services.com (The Right Reverend Colin James III)
>Newsgroups: comp.lang.ada,comp.lang.c++,comp.lang.c,comp.edu
             ^^^^^^^^^^^^^ ^^^^^^^^^^^^^ ^^^^^^^^^^^ ^^^^^^^^
             One           Two           Three       Four
>Subject: Hungarian notation:  the thread of choice for consummate boors
>Followup-To: comp.lang.ada,comp.lang.c++,comp.lang.c,comp.edu
              ^^^^^^^^^^^^^ ^^^^^^^^^^^^^ ^^^^^^^^^^^ ^^^^^^^^
              One           Two           Three       Four
[end from header]

>[groups trimmed to exclude those listed below]
>
>Several articles have already politely requested that the thread "Hungarian
>notation" be excluded from:
>
>comp.lang.eiffel
>comp.lang.modula2
>comp.lang.modula3
>
From my archives, and from searching both Alta Vista and Deja News, I can
only see *ONE* request from you that this thread be removed from
comp.lang.eiffel *ONLY*. Either you are mistaken about requesting Modula-2
and -3 be removed, or your other messages have fallen down a big black
hole.

>What is remarkable is how selfish (and disrespectful of others) the
>propagators of the thread are in ignoring such requests.
>
I suspect that many people are too lazy (or have poor newsreading software)
to check if they are cross-posting, or just plain missed your previous
requests to trim the messages. Posting a message doesn't guarantee everyone
in the whole world will see it. See my previous paragraph about my failure
to find the request you posted.

>Such notorious posters as [name removed]
>among others, rank right up there in forcing their irrelevant and
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>queer opinions on more than three usenet groups, namely seven, which is the

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>height of rudeness and bad manners.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Well, you've managed four. Where do you rank? (I've trimmed follows-up to
avoid me being the pot calling the kettle black).

>
>What follows is that the propagators are in fact consummate boors, and are
>best advised to "get a life" and to stop wasting everyone's time, including
>their own.
>

From your header I see:

>X-Newsreader: Forte Agent .99d/32.182

Upgrade to version .99e and you'll get kill files for free. Just press
Ctrl+K, type "subject: hungarian", and you will never again see any
"consummate boors" talking on this subject ever again.

Ken

Re: Hungarian notation: the thread of choice for consummate boors

[Jon Hornstein]

Dr. Dimitri Vulis,

I find your comments very offensive in the extreme and I have to
disqualify your opinon and comments as that of the rantings of a
hyterical lunatic. 

Why anyone would believe your rantings especially directed to the
individual Robert Dewar, puts discredit on all NYU academic and
administrative staff.

Personally I've never met Robert Dewar nor have I been in close enough
proximity to smell his flesh.  The question begs perhaps your strange
congnitive reasoning could be as a result of close proximity to
"mutant pigs" .

When  I was a student both in High School and university I was
required to buy textbook written by staff, and generally the material
was 2nd rate and expensive. I'm sure the staff would have assured us
that we too would be disadvantaged if we didn't buy their material.

dlv@bwalk.dm.com (Dr. Dimitri Vulis) wrote:

>>Several articles have already politely requested that the thread "Hungarian
>>notation" be excluded from:
>>
>>comp.lang.eiffel
>>comp.lang.modula2
>>comp.lang.modula3
>>
>>What is remarkable is how selfish (and disrespectful of others) the
>>propagators of the thread are in ignoring such requests.

>ADA contractors are the peasants of the computing landscape.

>>Such notorious posters as Robert Dewar, NYU academic and Ada compiler
>>vendor, among others, rank right up there in forcing their irrelevant and
>>queer opinions on more than three usenet groups, namely seven, which is the
>>height of rudeness and bad manners.

>I concur, with one correction.  I used to know Dewar personally and he's
>anything but "academic".  The fact that he posts to Usenet from a New York
>University address reflects badly on that institution, especially when
>Dewar uses it to peddle his "warez".

>>What follows is that the propagators are in fact consummate boors, and are
>>best advised to "get a life" and to stop wasting everyone's time, including
>>their own.

>Another good advice to Dewar is to lose a lot of weight. He looks (and smells)
>like a mutant pig.  I spoke with two students who took classes with Dewar at
>NYU, both of whom alleged that a) Dewar knew less than some students about
>the subject matter he was hired to teach, b) Dewar implied that buying his
>software products may affect a student's final grade in his course.

Re: Hungarian notation

[Ralph Silverman]

Kevin Cline (kcline@sun132.spd.dsccc.com) wrote:
: In article <dewar.832851446@schonberg>, Robert Dewar <dewar@cs.nyu.edu> wrote:
:  >.I don't know where this myth comes from.  In my 20+ years in
:  >.academia, I have NEVER met a software teacher who considered
:  >.uncommented code to be acceptable.  Practically everyone tries
:  >.to get across the message "write the comments first, and then
:  >.the code".

: How much time do you spend showing your students how to 
: write useful comments, or demonstrating good coding style?

: Is Kernighan & Plaugher's "The Elements of Programming Style" 
: a required or suggested text at NYU?

: This is a subject that seems to be largely ignored in undergraduate
: curricula.  The developers that do know how to comment seem to have
: learned by example.

:  >In fact the anti-comment attitude comes from the trenches rather than from
:  >the ivory tower. 
:  >The main argument seems to be that since no one can ever
:  >manage to maintain comments properly, it is better to have no comments, or
:  >at least to minimize comments. I strongly disagree, and feel that it is
:  >better still to keep the comments up to date. A bad comment is a bug, as
:  >serious as any other latent bug in the "real" code, and programmers have
:  >to start thinking that way.

: Comments should rarely require maintainence.  Largely they should be
: limited to describing a class and it's relationship to other classes,
: or describing the inputs, outputs, preconditions and postconditions
: for an entire method.  Few methods should be so complex that they
: require additional comments describing the method implementation.

:  >Yes of course it is hard to keep comments up to date -- there are many
:  >hard things about programming, this is one of them.
:  >
:  >To see the anti-comment view, look at section 3.3 of AQ&S (one of the few
:  >sections of this document that I am not fond of). It starts by saying
:  >
:  >  "Comments in source text are a controversial issue"  (!)
:  >
:  >and then goes on to present what supposedly is a balanced discussion on this
:  >issue that to my taste is far too anti-comment. Some excerpts:
:  >
:  >  "There are argments both for and against the view that comments
:  >   enhance readability"
:  >
:  >  "Comments should be minimized"
:  >
:  >  "source text should .. so that little additional commentary is needed"
:  >
:  >There is nothing exactly *wrong* with any of these statements, but the
:  >general tone adds up to me to be far too anti-comment.

: I really liked this section.  I thought it was very important to
: counter the typical methodologies of 2167A DoD software projects, which
: had a tendency to have rules like "one comment for every five lines of code".
: Maybe Mr. Dewar has been fortunate enough to have never worked on a software
: developed using DoD 2167A methodology.

: >As Peter says, most teachers stress comments. I certainly give zero to any
: >assignment that is uncommented, and take marks off for incompetent, incorrect
: >or annoyingly useless ("increment I") comments.

: Most teachers tell students to comment.  Few seem interested in telling
: students how to write useful comments.  

:  >To me good comments are essential, the code can only tell you what it does
:  >and how at a level of abstraction matching the code. Good comments tell you:
:  >
:  >   a) what the code is doing at a higher level of abstraction
:  >   b) why you did what you did
:  >   c) why you didn't do something else
:  >
:  >obviously code cannot be self-documenting in these three aspects.

: Agreed!!  But these comments seldom require maintainence.  Most
: maintainence involves either fixing bugs in old code, or adding
: new features to old code, presumably by adding new methods.
: These activities should seldom require changing existing comments.

: Less frequently, implementation decisions will change, and these
: changes should be documented.

:  >Of course I agree that incorrect or inconsistent or out-of-date comments
:  >are a menace, but that's an argument for making sure the comments are
:  >correct, consistent and up-to-date, not for eliminating them!
:  >
:  >Incidentally, I also follow Peter's rule of never helping with uncommented
:  >code, and in fact if students show me uncommented code, I take marks off
:  >the assignment no matter WHAT is eventually handed in, since I insist
:  >that coments must be written as part of the process of coding, not as an
:  >after-thought. In practice, this works very well, since I use email to
:  >give continuous feedback to students on early versions of their assignments,
:  >and they find this feedback valuable enough to be worth the nuisance of
:  >commenting their code!

: That's good.  Presumably you are giving them feedback on their commenting
: and coding style as well.  Your students should be well-prepared.
: -- 
: Kevin Cline

--
*********begin r.s. response*************

	the idea,
	that
		comments should
		outlive and outlast
			original code
		when that code has been modified...
	is extremely horrifying and bizarre!

	however,
	this does raise an intersting question...
		version control for comments!

*********end r.s. response***************
Ralph Silverman
z007400b@bcfreenet.seflin.lib.fl.us

Re: Hungarian notation

[Richard A. O'Keefe]

z007400b@bcfreenet.seflin.lib.fl.us (Ralph Silverman) writes:

>*********begin r.s. response*************

>	the idea,
>	that
>		comments should
>		outlive and outlast
>			original code
>		when that code has been modified...
>	is extremely horrifying and bizarre!

>	however,
>	this does raise an intersting question...
>		version control for comments!

The indentation,
of r.s.
	is unusual
and unhelpful.		(:-)

What is bizarre about the notion?  I often have big comments
explaining the purpose, assumptions, and interface of a module.
These comments almost always survive major changes to the
implementation.

They are in the source file for two reasons:
(a) so that I can read them while I'm working on the module
    and am reminded of what I'm supposed to be doing
(b) so that if some change _does_ invalidate a comment, the
    comment is there handy for me to revise.

I don't see any special problem for version control.
*All* documents used in the construction of a software system
are kept under version control, ideally under configuration management.

-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

Re: Hungarian notation

[James McKim]

In article <4p49vq$etm@nntp.seflin.lib.fl.us> z007400b@bcfreenet.seflin.lib.fl.us (Ralph Silverman) writes:

[...]

>
>	the idea,
>	that
>		comments should
>		outlive and outlast
>			original code
>		when that code has been modified...
>	is extremely horrifying and bizarre!

Um, well, not to me, or at least not in all cases. If the comments
represent the _specification_ of a routine as opposed to the implementation,
it is quite common for the code to evolve substantially with no change
to the comments.

I'm reading this in comp.lang.eiffel. To a limited extent, Eiffel supports
the compilation of rigorous comments that specify a feature. In the ideal
this means that if the code and the comments do not remain synchronized
you usually discover the problem very quickly.

>
>	however,
>	this does raise an intersting question...
>		version control for comments!
>
>*********end r.s. response***************
>Ralph Silverman
>z007400b@bcfreenet.seflin.lib.fl.us
>

Hope this helps,
-- Jim

-- 

*------------------------------------------------------------------------------*
Jim McKim  (860)-548-2458     Co-editor of Eiffel Outlook 
Internet:  jcm@hgc.edu        Subscribe early and often!

Re: Hungarian notation

[Ralph Silverman]

James McKim (jcm@hgc.edu) wrote:
: In article <4p49vq$etm@nntp.seflin.lib.fl.us> z007400b@bcfreenet.seflin.lib.fl.us (Ralph Silverman) writes:

: [...]

: >
: >	the idea,
: >	that
: >		comments should
: >		outlive and outlast
: >			original code
: >		when that code has been modified...
: >	is extremely horrifying and bizarre!

: Um, well, not to me, or at least not in all cases. If the comments
: represent the _specification_ of a routine as opposed to the implementation,
: it is quite common for the code to evolve substantially with no change
: to the comments.

: I'm reading this in comp.lang.eiffel. To a limited extent, Eiffel supports
: the compilation of rigorous comments that specify a feature. In the ideal
: this means that if the code and the comments do not remain synchronized
: you usually discover the problem very quickly.

: >
: >	however,
: >	this does raise an intersting question...
: >		version control for comments!
: >
: >*********end r.s. response***************
: >Ralph Silverman
: >z007400b@bcfreenet.seflin.lib.fl.us
: >

: Hope this helps,
: -- Jim

: -- 

: *------------------------------------------------------------------------------*
: Jim McKim  (860)-548-2458     Co-editor of Eiffel Outlook 
: Internet:  jcm@hgc.edu        Subscribe early and often!

--
************begin r.s. response**************

	surely there is a morass effect here...
	whereby comments require comments
	as code is modified
	and
	whereby comments are 'kind of' applicable...
	since such are not vetted automatically
	by a compiler or assembler no systematic
	minimal order or organization is imposed!

	(there is an old working class advisory...
		'look busy'
	 how much more could such putative
	 standards achieve than that?)

************end r.s. response****************
Ralph Silverman
z007400b@bcfreenet.seflin.lib.fl.us

Re: Hungarian notation

[Jeff Dege]

On 23 May 1996 07:40:11 -0400, Robert Dewar (dewar@cs.nyu.edu) wrote:

: In fact the anti-comment attitude comes from the trenches rather than from
: the ivory tower. The main argument seems to be that since no one can ever
: manage to maintain comments properly, it is better to have no comments, or
: at least to minimize comments. I strongly disagree, and feel that it is
: better still to keep the comments up to date. A bad comment is a bug, as
: serious as any other latent bug in the "real" code, and programmers have
: to start thinking that way.

    I see absolutely no gain from insisting on useless comments, and
most of the comments I see are useless.  The code is a complete specification
of what the program is doing, and duplicating any of that information is
pointless.

    What the code doesn't specify is _why_ the code is behaving in
a certain way.  _That_ is what needs to be commented.  But I've seen
code that was well more than half comments that left me with no
idea as to what the code was supposed to do, let alone why it was
written in a certain way.  But these are the questions that the
maintenance programmer is going to ask.

: Yes of course it is hard to keep comments up to date -- there are many
: hard things about programming, this is one of them.

    I find that comments about the purpose of code becomes obsolete much
more slowly than comments about what the code is doing.

: To me good comments are essential, the code can only tell you what it does
: and how at a level of abstraction matching the code. Good comments tell you:
: 
:    a) what the code is doing at a higher level of abstraction
:    b) why you did what you did
:    c) why you didn't do something else
: 
: obviously code cannot be self-documenting in these three aspects.

Exactly.

-- 
  Friendship is born at that moment when one person says to another:
  "What!  You, too?  Thought I was the only one."
                                             -C.S. Lewis

Re: Hungarian notation

[Warren Young]

dewar@cs.nyu.edu (Robert Dewar) wrote:

>  "Comments should be minimized"

Just wanted to comment here: I'm all for comments (about 30% of the
lines in my recent projects are whitespace or comments), but I do
agree with this.  I remember seeing one code module that had one
comment _per line of code_, and most of the comments were multi-line!
There was one section where each line had a six-line or better
comment.

I think comments force you to give your code a second thought.  An old
aphorism goes, "The best way to learn something is to try and teach it
to someone else," and a comment is your way of teaching future
maintenance programmers about your code.  I've corrected many
potential problems because I did some rethinking after trying to put a
comment on it.  The main example of this is a bit of code being too
complex.  If I have to put a 10-line comment on fewer lines of code
just to adequately explain it, it's probably too complex, and I end up
re-writing it to be clearer.  Often, the code is actually more concise
and/or smaller/faster as a result.

Getting back to that overly-verbose module, I think those comments
indicate a programmer that shares my basic views, but didn't actually
understand what it was they were writing.  In essence, they put every
interaction into those comments, stuff that would be a given to
someone who knew the underlying subsystems.  It'd be like commenting
every printf() or cout to take into account what they _might_ do with
the data.  That's great if the maintenance programmers don't
understand these basic facilities, but horrible when they do.

I don't know where it was, but I once read of a study that tested code
comprehension, plotted against the comment density.  It turns out that
the optimal density is one comment per four lines of code (I guess 10
comment lines per 40 lines of code would be OK, too) -- any fewer than
that caused obvious problems, but any more caused problems too,
because the subject had to plow through more verbosity to glean the
salient points of the code.

And speaking of verbosity, I've said quite enough already.

= Warren -- http://www.cyberport.com/~tangent

Re: Hungarian notation

[Norman H. Cohen]

In article <31b07448.390945509@sqarc.sq.com>, willer@carolian.com
(Steve Willer) writes: 

|> ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe) wrote: 
|>
|> >I recently bought "The Microsoft(R) Manual of Style for Technical
|> >Publications".  There is some very good stuff in there.  It introduced
|> >me to a term I didn't know: "callout" (basically, you have a diagram
|> >and a legend and a line that connects the legend to the place in the
|> >diagram it comments on).
|>
|> This sounds interesting, but I don't really understand what you mean
|> here. Could you give an example of this?

"Callout" is a standard typographical term for the symbol that appears in
running text (e.g. a superscript, an asterisk, or a dagger) to direct you
to a footnote.

--
Norman H. Cohen    ncohen@watson.ibm.com

Re: Hungarian notation

[Bob Rodgers]

nreitzel@lonestar.jpl.utsa.edu (Norman L. Reitzel   ) wrote:
>>> Hungarian Notation is an excellent concept, but I am sure that it will be
>>> appreciated only by the programmers who have to work with serious code and
[...]
>>B.S!!  It is a b-a-a-a-a-a-d idea.  It is an idiotic coding standard.  In "Programming Pearls," 
[...]
>What's worse, Arne, somebody will change the type, say from szShortSTring 
>to pszReallyLongString, find that it's referenced a zillion times, and 
>"fix" it by changing the name BACK, and then changing some (but not all) 

That's not a good example (because it's semantically harmless, and
because search & replace will handle it quite quickly, even on
multiple files).  

On the other hand, suppose one decided to change from a signed to
unsigned float?  Or from an int to a float?   

Hungarian *forces* the programmer to verify that things are right, at
least, right on a superficial level.   

Good programmers don't need a naming scheme to force them to write
good code.  Unfortunately, most programmers (including those paid to
program) aren't good programmers.

For most programmers, warnings (conversion, etc.) aren't sufficient --
too many of them ignore or (worse) disable them.  This is almost
routine.  I've seen people work this way: the first thing they do is
disable conversion warnings, signed/unsigned warnings, etc.  These are
not kids with compilers, but people being paid to develop apps that
that will need to be maintained for the next ten or more years.

What it comes down to is, hungarian naming is an excellent idea for
companies that hire programmers of low to middle ability.  It cuts
down on their errors in development and long-term maintenance costs.

That "good" programmers uses warning level 4 and seek to compile with
zero errors or as close to zero as possible is a given.  That the
majority of programmers do neither is, on the other hand, quite
obvious.  We need only look at the quality of software than sits on
store shelves.  

Run Netscape lately?  Some of those crashes, of which there are way,
way too many, look oddly like someone writing to an invalid pointer,
something that should have been caught a long time ago or never
present in the first place.

If you are a company hiring mid-low skilled programmers (and lets face
it: we *all* start off low and mid-skilled,, it is only experience &
practice that helps us improve), hungarian provides a solution to at
least part of several problems: code maint. (forcing developers to
check as they develop, and not "assume" that changes work, especially
on multiperson projects where idiots routinely integrate their code
changes without even checking to see if they compile), code
readability (inexperienced programmers often "shuffle and add" instead
of scrapping bad code and rewriting), and so on.

Hungarian isn't "bad" -- it's just not *good* for some programmers.

>it does it is an error waiting to happen.  The rude concept of 
>"self-documenting" code belongs in an ivory tower with those who teach, 
>not in the trenches with those of us who DO.

Well, we agree here.


- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
http://www.wam.umd.edu/~rsrodger                     homepage & gallery
http://www.wam.umd.edu/~rsrodger/project.htm       rsrodger@wam.umd.edu    

Re: Hungarian notation

[Matt Kennel]

Bob Rodgers (rsrodger@wam.umd.edu) wrote:
: Run Netscape lately?  Some of those crashes, of which there are way,
: way too many, look oddly like someone writing to an invalid pointer,
: something that should have been caught a long time ago or never
: present in the first place.

Hungarian doesn't fix this.  A garbage collector does.

Re: Hungarian notation

[Bob Rodgers]

mbk@caffeine.engr.utk.edu (Matt Kennel) wrote:
>Bob Rodgers (rsrodger@wam.umd.edu) wrote:
>: Run Netscape lately?  Some of those crashes, of which there are way,
>: way too many, look oddly like someone writing to an invalid pointer,
>: something that should have been caught a long time ago or never
>: present in the first place.

>Hungarian doesn't fix this.  A garbage collector does.

Hungarian, at least, keeps arrays and pointers clear.  However, I
agree, and the cost of a good garbage collector is trivial.  

Re: Hungarian notation

[Peter Seebach]

In article <4o1go0$jsd@cville-srv.wam.umd.edu>,
Bob Rodgers <rsrodger@wam.umd.edu> wrote:
>Hungarian, at least, keeps arrays and pointers clear.  However, I
>agree, and the cost of a good garbage collector is trivial.  

Yes, there's a good one free from PARC for us lowly C programmers.

Uhm.  How does Hungarian keep arrays and pointers clear?

	void foo(void) {
		int aryFoo[10];
		bar(aryFoo);
	}

	void bar(int aryParam[10]) {
		return;
	}

is clearly wrong, as the parameter of bar is a pointer, not an array;
yet, if you correctly note it as int *piParam, or whatever, you will have
what looks, in the notation, to be a conflict of types, although there
isn't one.

-s
-- 
Peter Seebach - seebs@solon.com - Copyright 1996 Peter Seebach.
Unix/C Wizard - send mail for help, or send money for consulting!
Unsolicited email is not welcome, and will be billed for at consulting rates.
The *other* C FAQ - http://www.solon.com/~seebs/c/c-iaq.html

Re: Hungarian notation

[Steve Willer]

mbk@caffeine.engr.utk.edu (Matt Kennel) wrote:

>: Run Netscape lately?  Some of those crashes, of which there are way,
>: way too many, look oddly like someone writing to an invalid pointer,
>: something that should have been caught a long time ago or never
>: present in the first place.
>
>Hungarian doesn't fix this.  A garbage collector does.

Neato! So I guess there is one and only one solution to the problem of
invalid pointers!

Re: Hungarian notation

[Richard A. O'Keefe]

willer@carolian.com (Steve Willer) writes:
>Neato! So I guess there is one and only one solution to the problem of
>invalid pointers!

Let me put it this way:
	IUnknown::AddRef
and	IUnknown::Release
are _not_ the solution.

-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

Re: Hungarian notation

[Steve Willer]

ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe) wrote:

>willer@carolian.com (Steve Willer) writes:
>>Neato! So I guess there is one and only one solution to the problem of
>>invalid pointers!
>
>Let me put it this way:
>	IUnknown::AddRef
>and	IUnknown::Release
>are _not_ the solution.

Certainly, I am far from being COM's biggest fan. But the point I'm
making is that garbage collection is not a perfect solution, nor is it
the one and only solution. No matter what the scheme (gc, ref-counting,
etc.), pointers can still get scrambled.

I have personally been quite successful with setting rules of ownership
and sticking by them. With the primary use of auto_ptrs and references,
I don't have problems with dangling pointers and the like. HOWEVER, in
order to properly use these different argument types without problems, I
either need a perfect memory or a good naming convention. I don't have a
perfect memory.

This setup won't work well in C, but it works very well for me in C++.
Here's the relevant part of my own coding standard:


1.	Function argument types

When designing function interfaces, keep these points in mind:

a)	All "input" arguments should be first, followed by
"input/output" arguments and then followed by "output" arguments. It may
be necessary to adjust this order to allow consistency with functions of
the same name, and default arguments may also force a reordering.

b)	Arguments must be declared const as often as possible. In other
words, restrict the argument as much as you can.

c)	In C++, if ownership of an object is being transferred, the
argument must be an auto_ptr passed by value. If ownership is not being
transferred, then the argument must be a reference. The only exception
to this is when it must be possible to give a NULL (obviously, the
argument should be declared as a pointer in this case). However, rethink
the necessity of a NULL-compatible argument before using a pointer
argument.

Re: Hungarian notation

[Michael Furman]

In article <4nsgct$c3l@cville-srv.wam.umd.edu>, rsrodger@wam.umd.edu says...
>  [.....]
>What it comes down to is, hungarian naming is an excellent idea for
>companies that hire programmers of low to middle ability.

I believe the much better idea for such company - just close itself. Or
switch to another kind of business that does not have any relation to
creating software.

Michael Furman,                       (603)893-1109
Geophysical Survey Systems, Inc.  fax:(603)889-3984
13 Klein Drive - P.O. Box 97          engr@gssi.mv.com 
North Salem, NH 03073-0097            71543.1334@compuserve.com
---------------------------------------------------------------

Slander (was: Hungarian notation)

[Graham Perkins]

Bob Rodgers wrote:
> nreitzel@lonestar.jpl.utsa.edu (Norman L. Reitzel   ) wrote:
> >it does it is an error waiting to happen.  The rude concept of
> >"self-documenting" code belongs in an ivory tower with those who teach,
> >not in the trenches with those of us who DO.
> 
> Well, we agree here.

Please desist this slander.

The teaching of good software design and development practices is a difficult
business and there is little universal agreement on what those concepts include,
never mind how best to teach them.  Academia does try hard to deliver.  It
may be unfortunate that there are some teachers with lower software expertise
who get dumped with some introductory programming teaching on the assumption 
that those with the thinnest background should be given the "easiest" end
of the subject to teach.  However there is plenty of that in industry too, with
actual coding and code maintenance often being left to the most junior staff
with narrowest experience.  But I am not particularly interested in the huge
amount of bad commercial development that comes to light, except as object
lessons in what to avoid.

A glance through a few journals, magazines, and conference proceedings will
soon show up the huge contribution made to commercial software development
by intelligent and hard-working people working in academia, industry, or both.
These newsgroups will just become cluttered with insult-trading if we seek
every instance of poor practice and publicly slag it, especially if we then
tar a whole group with the same brush.

As for Hungarian notation, academics like myself are quite capable of taking
the helpful aspects (careful analysis of semantic structure of data space,
careful structuring of namespace to aid the reader's understanding of the
data space) and dropping those specific recommendations which seem designed
to assist assembler language programmers.  It then becomes interesting to
look at different languages and their environments to see how much direct 
support they give for organising naming schemes and how much you have to 
introduce via comments, name prefix/postfix, or special tools.

> > The rude concept of
> > "self-documenting" code belongs in an ivory tower

Presumably this should be "crude" not "rude".
The concept of *totally* self-documenting code belongs nowhere.

Perhaps the poster has facilely misninterpreted recommendations to
place meaningful information in source code to aid the reader as a
diktat to avoid other forms of documentation.

Re: Slander (was: Hungarian notation)

[Richard A. O'Keefe]

Graham Perkins <grp@dmu.ac.uk> writes:
>As for Hungarian notation, academics like myself are quite capable of taking
>the helpful aspects (careful analysis of semantic structure of data space,
>careful structuring of namespace to aid the reader's understanding of the
>data space) and dropping those specific recommendations which seem designed
>to assist assembler language programmers.  It then becomes interesting to
>look at different languages and their environments to see how much direct 
>support they give for organising naming schemes and how much you have to 
>introduce via comments, name prefix/postfix, or special tools.

It is worth noting that the first time I saw the idea of systematically
using prefixes written down was in a Xerox CSL ("blue and white") report
which I read in 1984.  I no longer recall the title or authors or when
it was written, but I think it may have come out of some of the early
Mesa work.  The report suggested having a project "namesmith" who would
manage the project glossary.  This predates "Hungarian" by several years.
There were three keys points that I recall:
    - build your identifiers out of words from the APPLICATION domain
    - if an abbreviation is a common term in the application domain use
      it, otherwise use abbreviations sparingly
    - to ensure that words and abbreviations are used consistently,
      maintain a project glossary and ensure that names in interfaces
      comply with this glossary.

Whatever is good in Hungarian long predates it.

(LClint can be used to check "Czech" and "Slovak" names...)

-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

Re: Slander (was: Hungarian notation)

[Tucker Taft]

Richard A. O'Keefe (ok@goanna.cs.rmit.EDU.AU) wrote:

: It is worth noting that the first time I saw the idea of systematically
: using prefixes written down was in a Xerox CSL ("blue and white") report
: which I read in 1984.  I no longer recall the title or authors or when
: it was written, but I think it may have come out of some of the early
: Mesa work.  

I believe the originator of "Hungarian notation" at Microsoft had earlier
worked at Xerox PARC, so there may be a connection...

: Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

-Tucker Taft   stt@inmet.com   http://www.inmet.com/~stt/
Intermetrics, Inc.  Cambridge, MA  USA

Re: Hungarian notation

[Peter Moylan]

Bob Rodgers (rsrodger@wam.umd.edu) wrote:

>On the other hand, suppose one decided to change from a signed to
>unsigned float?  Or from an int to a float?   

Since I'm reading this in the Modula-2 newsgroup, I can't
resist giving the obvious answer.  (You'd probably get a
similar answer from the Ada newsgroup.)

The answer is that it's a non-problem, because
 (a) it's internal implementation detail, and the change
     would not even be visible in the client modules;
 (b) in the affected module there wouldn't be all that much
     to check and/or change, unless you depart from accepted
     good practice and start writing huge modules;
 (c) if all else fails, the error is going to be picked
     up by the compiler, at which point the necessary changes
     are obvious.

Hungarian notation is an old-fashioned work-around for a
problem in an old-fashioned language.  The issue wouldn't
even arise if people didn't insist on sticking to 20-year-old
technology.

Even in C, there wouldn't be much of a problem if programmers
made sure that their names were tightly scoped.  Anyone
who creates a variable (or a type, or a procedure, etc.)
that's visible over a wide scope is asking for trouble, and
no amount of cosmetic massaging is going to remove the risk
of disaster in such a case.  And that's something that's been
known for years.  Anyone who's still writing code like that
ought to be taken out and GPF'd.

The real question is: why is this being posted to seven
different newsgroups?  It's very specifically a C problem,
and has little relevance to the rest of us.

--
Peter Moylan                           peter@ee.newcastle.edu.au
                  http://www.eng.newcastle.edu.au/ee/Moylan.html
OS/2 freeware list at 
      http://www.eng.newcastle.edu.au/ee/Moylan/os2/os2info.html

Re: Hungarian notation

[Ralph Silverman]

Steve Willer (willer@carolian.com) wrote:
: ok@goanna.cs.rmit.edu.au (Richard A. O'Keefe) wrote:

: >I am not the only person in this department who wishes that more of our
: >students had attained at least "advanced apprentice" English skills.  A
: >good creative writing course might work wonders, especially one of those
: >ones where you are taught how to _rewrite_.

: My own experience with some of my co-workers is that typing skills are
: very important as well. If the programmer has to hunt-and-peck at 20
: words a minute, they would be inclined to write minimal comments, log
: messages, etc., using abbreviations that nobody except themselves can
: understand. Plus, it promotes the naming of variables like "var",
: "evnt", etc.

: >This is, alas, painfully true.  There are too perishing many programmers.
: >What we need is more software engineers:  people who can not only produce
: >code that works but explain it so well that it keeps *on* working as the
: >necessary adaptive changes are made.  Show me someone who things that
: >computing is all about programming, and I'll show you someone whose test
: >plans aren't nearly good enough.

: And don't forget designs.

--
***********begin r.s. response**************

	i do not know what to
		'thing'
	about this...
	any help?

***********end r.s response*****************
Ralph Silverman
z007400b@bcfreenet.seflin.lib.fl.us

Re: Hungarian notation

[Richard Riehle]

On Thu, 16 May 1996, mAg wrote:

> Hungarian Notation is an excellent concept, but I am sure that it will be
> appreciated only by the programmers who have to work with serious code and
> maintain it for years. For others who write smaller programs, it may not
> even be necessary, because there is not need to convey the implementation
> specific stuff in the variable name, because they can shout and ask the
> other programmer in the next office...

  I initially disliked Hungarian notation.  But I have been programming
  long enough to know that my first impression of a new idiom is almost
  always influenced by my most current experience.

  Apparently,  Hungarian notation was invented in one department at
  Microsoft to help solve the traceability problem.  It apparently did
  well what it was supposed to do. Traceability in large-scale or
  complex C programs has always been a bit dicey.

  The question is whether we still have that original problem to solve.  I
  believe that traceability is not as much of a problem in Eiffel, Ada,
  or even C++. Fortunately, Eiffel and Ada can simply ignore Hungarian
  notation except when interfacing with C routines.  C++ remains mired in
  the tarpits of its ancestral language, C, so it is not easy to ignore
  the large body of code already develped using Hungarian notation.

  In any case, this notation is not so terrible as to cause permanent
  psychological damage, so I suggest we might as well just get used to it
  when we have to code in C or C++. Bring a sense of humor to it, and
  simply think of it as a "quaint" artifact of an earlier time.

  Richard Riehle

Re: Hungarian notation

[Laurent Guerby]

James> In article <4o1928$ngv@goanna.cs.rmit.EDU.AU>
James> ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe) writes:

James> |> Fifty years of programming language research, and we end up
James> with C++ ???

James> Sort of fitting, actually, since we are running on Intel
James> chips:-).  (Fifty years of computer architecture research...)

   Tssss. Great progress have been made in this field to build the
fastest hardware/software Intel 4004 emulator ! Of course progress to
build better instruction sets for faster programs are put a bit aside.

   ;-)

-- 
--  Laurent Guerby, student at Telecom Bretagne (France), Team Ada.
--  "Use the Source, Luke. The Source will be with you, always (GPL)."
--  http://www-eleves.enst-bretagne.fr/~guerby/ (GATO Project).
--  Try GNAT, the GNU Ada 95 compiler (ftp://cs.nyu.edu/pub/gnat).

Please keep Hungarian notation thread OUT of comp.lang.modula3

[Tim Mann]

Hungarian Notation has absolutely nothing to do with Modula-3.  No one writes
Modula-3 programs using Hungarian notation.  No one in comp.lang.modula3 cares
about it.  The other random C/C++ flames that erupt in this thread are of even
less interest.

I suspect the same holds true for the Ada, Eiffel, and Modula-2 groups, but
I can't speak for them.

Yes, I know how to use a kill file, so don't bother flaming me about that.

	--Tim

Re: Hungarian notation

[Robert I. Eachus]

In article <dewar.832851446@schonberg> dewar@cs.nyu.edu (Robert Dewar) writes:

  > Of course I agree that incorrect or inconsistent or out-of-date
  > comments are a menace, but that's an argument for making sure the
  > comments are correct, consistent and up-to-date, not for
  > eliminating them!

   I have a little tool that gets lots of workout.  It produces an
uncommented version of a source file.  (Actually it checks for and
keeps classification comments for obvious reasons, but eliminates all
the others.)   When debugging I read the commented source first, then
work from a printed copy of the uncommented listing.  I sometimes even
debug using uncommented versions.  Of course I then move any fixes to
the commented version, then add and repair comments as necessary.

   This allows me to live with source files that have three or more
lines of comments per actual source line.  (I think one to one is the
right balance during development, but as code is maintained, it needs
perhaps ten lines of comments per fix.)

--

					Robert I. Eachus

with Standard_Disclaimer;
use  Standard_Disclaimer;
function Message (Text: in Clever_Ideas) return Better_Ideas is...

Re: Hungarian notation

[James Kanze US/ESC 60/3/141 #40763]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 606 bytes --]


In article <4o1928$ngv@goanna.cs.rmit.EDU.AU> ok@goanna.cs.rmit.EDU.AU
(Richard A. O'Keefe) writes:

|> Fifty years of programming language research, and we end up with C++ ???

Sort of fitting, actually, since we are running on Intel chips:-).
(Fifty years of computer architecture research...)
-- 
James Kanze         Tel.: (+33) 88 14 49 00        email: kanze@gabi-soft.fr
GABI Software, Sarl., 8 rue des Francs-Bourgeois, F-67000 Strasbourg, France
Conseils, �tudes et r�alisations en logiciel orient� objet --
                -- A la recherche d'une activit� dans une region francophone

Re: Hungarian notation

[Paul J. Kossick]

James Kanze US/ESC 60/3/141 #40763 (kanze@lts.sel.alcatel.de) wrote:
: In article <4o1928$ngv@goanna.cs.rmit.EDU.AU> ok@goanna.cs.rmit.EDU.AU
: (Richard A. O'Keefe) writes:

: |> Fifty years of programming language research, and we end up with C++ ???

: Sort of fitting, actually, since we are running on Intel chips:-).
: (Fifty years of computer architecture research...)

Um...forgive me for interjecting, but what are the respective points of 
the above statements?

--
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Paul J. Kossick                         What you do for money sustains you
kossick@crl.com                         What you do for nothing defines you
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*

Re: Hungarian notation

[Raoul De Kezel]

kossick@crl.com (Paul J. Kossick) wrote:

>James Kanze US/ESC 60/3/141 #40763 (kanze@lts.sel.alcatel.de) wrote:
>: In article <4o1928$ngv@goanna.cs.rmit.EDU.AU> ok@goanna.cs.rmit.EDU.AU
>: (Richard A. O'Keefe) writes:

>: |> Fifty years of programming language research, and we end up with C++ ???

>: Sort of fitting, actually, since we are running on Intel chips:-).
>: (Fifty years of computer architecture research...)

>Um...forgive me for interjecting, but what are the respective points of 
>the above statements?

Um... I burst out laughing when I read the above. It might not have
been the point, but it was a very welcomed event.

--- Raoul

Re: Hungarian notation

[Ralph Silverman]

Peter Moylan (peter@fourier.newcastle.edu.au) wrote:
: Andy Ho-Fan Chan (andyc@procom.com) wrote:
: >In article <4o07o9$rfu@seagoon.newcastle.edu.au>, peter@tesla.newcastle.edu.au wrote:

: >>I adopted a policy, years ago, of never agreeing to help
: >>debug badly-documented code.  When I'm asked questions like
: >>"why doesn't my code work", my response is along the lines
: >>of "come back after you've inserted the comments, and we'll
: >>look at it then".  Half the time they don't come back, 
: >>because they discover the error themselves while debugging
: >>the comments.

: >Well, I guess they just don't want to comment the code and don't come to ask 
: >you question anymore.  I'm a student in CS, and I know what the students feel. 
: > When the project is dued soon and don't get the program works, do you still 
: >have time to comment to code?

: No argument with this ... we all know that that's what the
: students feel.  Almost invariably, the reason given for
: leaving out comments is "I don't have the time".

: The real question, however, is this: if you have to get something
: working quickly, do you still have time to NOT comment the code?

: Or, to put it another way: would you rather spend half an
: hour getting the comments right, or several days fighting
: with the debugger?

: This commenting business is not just an optional extra
: to make your code look pretty.  The main reason for doing
: a good job on the commenting is that it helps you code
: a lot _faster_.

: But <sigh!> many students - particularly the weaker students
: - never seem to learn this point.  Show them the easy way
: to get the job done, and they'll still stick stubbornly
: to the hard way.

: --
: Peter Moylan                           peter@ee.newcastle.edu.au
:                   http://www.eng.newcastle.edu.au/ee/Moylan.html
: OS/2 freeware list at 
:       http://www.eng.newcastle.edu.au/ee/Moylan/os2/os2info.html

--
**********begin r.s. response***********

	in developing software code
	one must satisfy a
		compiler
	or such...

	would it not be preferable to
	develop patterns of thought
	that work with the system than
	with the arbitrary preferences
	of a teacher!

**********end r.s. response*************
Ralph Silverman
z007400b@bcfreenet.seflin.lib.fl.us

Re: Hungarian notation

[jthorpe]

In <4p45kd$ea0@nntp.seflin.lib.fl.us>, z007400b@bcfreenet.seflin.lib.fl.us (Ralph Silverman) writes:


Never enough time - have often have I heard that, and outside of academic 
halls.

For many years I was in charge of all physical plant for a large school system.
I would get complaints from Principals that something hadn't been installed
properly, only to be told by the maintenance crew that 'We didn't have time".

My stock response was 'How the hell is it that you didn't have the time to
do it properly in the first place, but you are able to find plenty of time to fix 
the screwup?"  For that remark I was labelled as a miserble SOB.

They were probably correct <g>

Jim T.

Re: Hungarian notation

[Richard A. O'Keefe]

z007400b@bcfreenet.seflin.lib.fl.us (Ralph Silverman) writes:
>	in developing software code
>	one must satisfy a
>		compiler
>	or such...

Source code has at least two functions:
  - to instruct the computer how to solve a problem
  - to explain to a maintenance programmer how come it works

I have just been marking a number of student assignments, many of
which "satisfied the compiler" (the compiler did not produce any
error messages; the programm appeared to work on one test case)
but were seriously wrong about several points (typically if the
slightest thing failed the programs would go "insane").  In fact
many of the programs did _not_ satisfy _my_ compiler (lint &&
gcc -ansi -pedantic -O2 -Wall ...); the reason the programs
_appeared_ to satistfy the compiler was that they didn't ask the
compiler to check very much.

>	would it not be preferable to
>	develop patterns of thought
>	that work with the system than
>	with the arbitrary preferences
>	of a teacher!

Ah, but the teachers' preferences are NOT arbitrary!
*all* of the effective programmers I know write their comments
first, explaining what the code is for and how come it works,
and then write the code to fit the comments.

Except in the smallest of student assignments, a programmer has
to worry a *lot* about communicating with other *people*, and
even in student assignments, a program that ``works'' is of
little use if the teacher can't understand it.
-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

Re: Hungarian notation

[Chris Kuan]

Richard A. O'Keefe wrote:
> 
> Except in the smallest of student assignments, a programmer has
> to worry a *lot* about communicating with other *people*, and
> even in student assignments, a program that ``works'' is of
> little use if the teacher can't understand it.

I had to take a SAS program and convert it to C. While I was debugging
my program :-( I showed the code to the original programmer to 
see if I had misinterpreted an algorithm.

He said to me, "I don't know C, but I can understand this code."

One of the greatest compliments I have received in my brief 
professional career.

- Chris.

Re: Hungarian notation

[Ralph Silverman]

Richard A. O'Keefe (ok@goanna.cs.rmit.EDU.AU) wrote:
: z007400b@bcfreenet.seflin.lib.fl.us (Ralph Silverman) writes:
: >	in developing software code
: >	one must satisfy a
: >		compiler
: >	or such...

: Source code has at least two functions:
:   - to instruct the computer how to solve a problem
:   - to explain to a maintenance programmer how come it works

: I have just been marking a number of student assignments, many of
: which "satisfied the compiler" (the compiler did not produce any
: error messages; the programm appeared to work on one test case)
: but were seriously wrong about several points (typically if the
: slightest thing failed the programs would go "insane").  In fact
: many of the programs did _not_ satisfy _my_ compiler (lint &&
: gcc -ansi -pedantic -O2 -Wall ...); the reason the programs
: _appeared_ to satistfy the compiler was that they didn't ask the
: compiler to check very much.

: >	would it not be preferable to
: >	develop patterns of thought
: >	that work with the system than
: >	with the arbitrary preferences
: >	of a teacher!

: Ah, but the teachers' preferences are NOT arbitrary!
: *all* of the effective programmers I know write their comments
: first, explaining what the code is for and how come it works,
: and then write the code to fit the comments.

: Except in the smallest of student assignments, a programmer has
: to worry a *lot* about communicating with other *people*, and
: even in student assignments, a program that ``works'' is of
: little use if the teacher can't understand it.
: -- 
: Fifty years of programming language research, and we end up with C++ ???
: Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

--
**********begin r.s. response****************

	generally;
	if 
	students are writing code which works
	and,  which teachers can not understand
	without comments,
	then
		something is wrong with the school!!!

**********end r.s. response******************
Ralph Silverman
z007400b@bcfreenet.seflin.lib.fl.us

Re: Hungarian notation

[The Amorphous Mass]

On 7 Jun 1996, Ralph Silverman wrote:

> 	generally;
> 	if 
> 	students are writing code which works
> 	and,  which teachers can not understand
> 	without comments,
> 	then
> 		something is wrong with the school!!!
                                            ^^^^^^

  I                                                         think
                 you miss
 pelled

                                       "code



."

James Robinson.........................................james-robinson@uiowa.edu
   "To be prepared against surprise is to be /trained/.  To be prepared for
   surprise is to be /educated/."  --James Carse, _Finite_and_Infinite_Games_

Re: Hungarian notation

[Michael Furman]

In article <4p9cia$9v3@nntp.seflin.lib.fl.us>, 
z007400b@bcfreenet.seflin.lib.fl.us says...
> [.....]
>        generally;
>        if 
>        students are writing code which works
>        and,  which teachers can not understand
>        without comments,
>        then
>                something is wrong with the school!!!

How code can work but nobody can understand it? What does it mean that code
"works"? And how can you be sure that it does?
Code that "works" this way like a student who know all about some subject 
but just can't explain anything.

---------------------------------------------------------------
Michael Furman,                       (603)893-1109
Geophysical Survey Systems, Inc.  fax:(603)889-3984
13 Klein Drive - P.O. Box 97          engr@gssi.mv.com 
North Salem, NH 03073-0097            71543.1334@compuserve.com
---------------------------------------------------------------

Re: Hungarian notation

[Richard A. O'Keefe]

This is my last response to Ralph "the indenting is all my own invention"
Silverman before he goes into my killfile.

z007400b@bcfreenet.seflin.lib.fl.us (Ralph Silverman) writes:

>: Except in the smallest of student assignments, a programmer has
>: to worry a *lot* about communicating with other *people*, and
>: even in student assignments, a program that ``works'' is of
>: little use if the teacher can't understand it.

>	generally;
>	if 
>	students are writing code which works
>	and,  which teachers can not understand
>	without comments,
>	then
>		something is wrong with the school!!!

I see that Silverman doesn't pay a lot of attention to the details when
reading English.  He apparently didn't notice the scare quotes around
``works''.

Students often hand code in, insisting that it ``works'', because no
symptoms were produced on their PC.  Run it on a UNIX system, and an
instant segmentation violation often results.  (Dereferencing NULL.)
Or the assignment said that the program was supposed to work on UNIX,
but it crashes with file names having more than 8 letters.  In one
case, a student insisted that his text justification program (I did
not set that assignment) worked perfectly, until I pointed out that
when I fed the program its own source code it produced weird results.

As for teachers having to understand any random piece of code without
comments, get real.  Just last month a couple of students tried an
old "International Obfuscated C Contest": program on me.  It prints
the lyrics of "The Twelve days of Christmas".  I dug into it just far
enough to prove that it wasn't legal standard C and handed it back.

If it wasn't covered by privacy regulations, I would try some of our
2nd-year student code on you.  It is clear Mr Silverman has no idea
at all what student code can look like.

-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

Re: Hungarian notation

[Will Rose]

Richard A. O'Keefe (ok@goanna.cs.rmit.EDU.AU) wrote:
[...]
: Students often hand code in, insisting that it ``works'', because no
: symptoms were produced on their PC.  Run it on a UNIX system, and an
: instant segmentation violation often results.  (Dereferencing NULL.)
: Or the assignment said that the program was supposed to work on UNIX,
: but it crashes with file names having more than 8 letters.  In one
: case, a student insisted that his text justification program (I did
: not set that assignment) worked perfectly, until I pointed out that
: when I fed the program its own source code it produced weird results.

One partial cure for this, since I think most Unix systems have lint
somewhere, would be to feed the code through lint and ask the students
to explain and comment the subsequent listing.  On badly-written
programs, lint can get really tedious.  Personally, I just don't program
C without it, though.  Life's too short.

Will
cwr@crash.cts.com

Re: Hungarian notation

[Kevin Cline]

In article <4pioot$kae@goanna.cs.rmit.EDU.AU>,
Richard A. O'Keefe <ok@goanna.cs.rmit.EDU.AU> wrote:
>If it wasn't covered by privacy regulations, I would try some of our
>2nd-year student code on you.  It is clear Mr Silverman has no idea
>at all what student code can look like.

Actually, I think Mr. Silverman knows exactly what student code looks like:
It looks a lot like professional code.  Or should I say that a lot of
professionally written code looks like 2nd-year student code?

Maybe we should have a contest to find the worst examples of professionally
produced C++ code?  
-- 
Kevin Cline

Re: Hungarian notation

[Chris Engebretson]

In article <4pk29i$nhj@tpd.dsccc.com>, kcline@sun132.spd.dsccc.com (Kevin Cline) writes:

|> Actually, I think Mr. Silverman knows exactly what student code looks like:
|> It looks a lot like professional code.  Or should I say that a lot of
|> professionally written code looks like 2nd-year student code?
|> 
|> Maybe we should have a contest to find the worst examples of professionally
|> produced C++ code?  

Apologies in advance if I'm going way off-base here. :-)

In my place of work, at least, the worst examples of professionally produced
code (independent of the language that it's written in) usually don't come 
from coders with degrees in Computer Science.  Rather, they come from people
like remote sensing scientists and electrical engineers.  These individuals
have the technical know-how to develop algorithms and justify their correct-
ness, but they tend to have difficulty expressing them eloquently and
efficiently when it comes down to actually writing the code.  Comments are
sparse if not totally nonexistant, variable names are not descriptive, and
"goto"s are a dime-a-dozen.

As I often have occasion to maintain code like this, I gain a deeper
appreciation for some of my college programming-oriented classes, because
they serve a dual purpose.  Not only do they introduce you to and allow you
to get your hands dirty with various topics and theories (i.e., compiler
fundamentals and language translation), but by requiring you to write several
thousand lines of code to successfully complete the class, they also make it
crystal-clear how important such things as efficiency, structure, and
documentation really are.  Most of the scientists I know who play a dual role
as a programmer really haven't had this kind of exposure; in fact, with
regards to C/FORTRAN, a good number of them are self-taught.  As a result,
the code that they produce works, but not as well as it probably could (and
should!), and it's certainly not as clear as it should be.

It's been my experience and observation that our academic community is
beginning to require more computer science "techie" courses from its 
scientific and engineering students.  And this is a Good Thing, because a
good deal of the world's existing base of code was not written by individuals
with strong Computer Science backgrounds, and that's not going to change
anytime in the near future.  Since these scientists and engineers will
inevitably be asked to express themselves in the form of a high-level
computer language, this experience will prove invaluable, both to themselves
and to the individual(s) whose job it is to maintain that code.

PS: Of course, this is not to say that a scientist with little background in
Computer Science can't write truly excellent code, and I'm certainly not
saying that when a student graduates with a degree in Computer Science, he/she
automatically will write wonderful programs, because we all know _that_ isn't
true.  But the old saying holds true: Practice makes perfect.

--
/*-------------------------------------------------------------
Chris Engebretson // CSB - SED - Scientific Systems Development
United States Geological Survey   -   National Mapping Division
Mundt Federal Building, USGS EROS Data Center
Sioux Falls, SD 57198  http://edcwww.cr.usgs.gov/eros-home.html
email: engebret@edcserver1.cr.usgs.gov      phone: 605-594-6829
-------------------------------------------------------------*/

Re: Hungarian notation

[Ralph Silverman]

Kevin Cline (kcline@sun132.spd.dsccc.com) wrote:
: In article <4pioot$kae@goanna.cs.rmit.EDU.AU>,
: Richard A. O'Keefe <ok@goanna.cs.rmit.EDU.AU> wrote:
: >If it wasn't covered by privacy regulations, I would try some of our
: >2nd-year student code on you.  It is clear Mr Silverman has no idea
: >at all what student code can look like.

: Actually, I think Mr. Silverman knows exactly what student code looks like:
: It looks a lot like professional code.  Or should I say that a lot of
: professionally written code looks like 2nd-year student code?

: Maybe we should have a contest to find the worst examples of professionally
: produced C++ code?  
: -- 
: Kevin Cline

--
************begin r.s. response**************

	a program that works has,
	in this,  taken on a
		life of its own
	that places it,  in a way,
	outside the hands of its
	creator...

	perhaps it would be possible
	to develop a study of software
	independent of the intentions
	and personality of the creator
	of the software...which focuses
	on its characteristics as software!

	in such an
		impersonal
	study of software...preference might
	be given to avoidance of evaluation of
	provenance,  comments and the like!

	objective,  impersonal evaluation of
	software is largely attainable and might
	have real uses!

************end r.s. response****************
Ralph Silverman
z007400b@bcfreenet.seflin.lib.fl.us

Re: Hungarian notation

[Bob Rodgers]

kcline@sun132.spd.dsccc.com (Kevin Cline) wrote:
>Actually, I think Mr. Silverman knows exactly what student code looks like:
>It looks a lot like professional code.  Or should I say that a lot of
>professionally written code looks like 2nd-year student code?

>Maybe we should have a contest to find the worst examples of professionally
>produced C++ code?  

You mean code that has pointer errors of the sort that even first
semester CS students are expected to avoid?

If we have a pool, put me down for "Netscape" and "Delrina."

Re: Hungarian notation

[Matt Kennel]

Bob Rodgers (rsrodger@wam.umd.edu) wrote:
: kcline@sun132.spd.dsccc.com (Kevin Cline) wrote:
: >Actually, I think Mr. Silverman knows exactly what student code looks like:
: >It looks a lot like professional code.  Or should I say that a lot of
: >professionally written code looks like 2nd-year student code?

: >Maybe we should have a contest to find the worst examples of professionally
: >produced C++ code?  

: You mean code that has pointer errors of the sort that even first
: semester CS students are expected to avoid?

: If we have a pool, put me down for "Netscape" and "Delrina."

First semester CS students avoid such things by using Scheme or at least
anything with a garbage collector. 

Clueless professionals think they're past such things, and believe that
as in Lake Wobegon, they are all above average. 

First semester physics laboratory students are told over and over "Check
your units! Dimensional analysis!"

Professionals still have to do that all the time.  
Always: if the units are wrong, the answer is wrong. 

--
Matthew B. Kennel/mbk@caffeine.engr.utk.edu/I do not speak for ORNL, DOE or UT
Oak Ridge National Laboratory/University of Tennessee, Knoxville, TN USA/ 
*NO MASS EMAIL SPAM* It's an abuse of Federal Government computer resources
and an affront to common civility.

Re: Hungarian notation

[Giuliano Carlini]

In <4pmvs1$15v@gaia.ns.utk.edu> mbk@caffeine.engr.utk.edu (Matt Kennel)
writes: 
>First semester CS students avoid such things by using Scheme or at
least
>anything with a garbage collector. 
>
>Clueless professionals think they're past such things, and believe
that
>as in Lake Wobegon, they are all above average. 

What is the opposite of Clueless? Clued?

Damn straight. I wish more people would use garbage collectors. And not
just cause I've written one. If our "profession" used GC it would do
much better in its ethical duty to ship products with very low bug
rates.

g

Re: Hungarian notation

[Jeff Dege]

On 12 Jun 1996 17:47:45 GMT, Matt Kennel (mbk@caffeine.engr.utk.edu) wrote:
: First semester CS students avoid such things by using Scheme or at least
: anything with a garbage collector. 

I've found that many novices figure that because they have a system with
garbage collection they no longer need to worry about resource allocation
and deallocation.  It ain't necessarily so.
 
: Clueless professionals think they're past such things, and believe that
: as in Lake Wobegon, they are all above average. 

-- 
  Friendship is born at that moment when one person says to another:
  "What!  You, too?  Thought I was the only one."
                                             -C.S. Lewis

Re: Hungarian notation

[Richard Green]

kcline@sun132.spd.dsccc.com (Kevin Cline) wrote:

>Maybe we should have a contest to find the worst examples of professionally
>produced C++ code?  
>-- 
>Kevin Cline

Aren't we missing the point here ? Surely coding standards (
notatation, naming conventions etc.) differ for every piece of code
one writes - for example, if I want to write a trivial c program to do
strip something from the input and do something "interesting" on the
output side (i.e. a sort of unix "tail -f | grep | etcetc", I'll
probably write it using one character var names, if's without {}, and
all those other possible but bad practice things, however, if I'm
writing a piece of code for a client which does something even more
trivial, I'll name the function logically, comment it , date it,
perhaps even write a list of presuppositions, maybe even put the
prefix p_ before every pointer variable if they want me to. After all,
they're paying the rent.

Being a good programmer isn't just coding, in fact I think I spend
only 20% of my time coding "at the keyboard", and some of the time
thinking about all the ramifications over my code when it gets
released, _including_ the support and maintenance issues, but probably
the majority planning and designing.

When it comes to the debate on this  thread, the expression "Horses
for courses" springs to mind.

Richard.
#include <std_disclaimer.h>

+----------------------------------------------------------------+
These fews are mine and I reserve the right to argue against them 
at a later date when I realise that sometimes I can make mistakes.

Richard Green - 101635,170@compuserve.com (or is it compu$$$$$e ?! :)

+----------------------------------------------------------------+

Re: Hungarian notation

[Ralph Silverman]

The Amorphous Mass (robinson@green.weeg.uiowa.edu) wrote:
: On 27 May 1996, Jeff Dege wrote:

: > On 27 May 1996 00:44:35 GMT, Peter Moylan (peter@fourier.newcastle.edu.au) wrote:
: > : This commenting business is not just an optional extra
: > : to make your code look pretty.  The main reason for doing
: > : a good job on the commenting is that it helps you code
: > : a lot _faster_.
: > : 
: > : But <sigh!> many students - particularly the weaker students
: > : - never seem to learn this point.  Show them the easy way
: > : to get the job done, and they'll still stick stubbornly
: > : to the hard way.
: > 
: > How many teachers _teach_ this?  I've been through a BS program in CS, and
: > I'm half-way through an MS program in SE, and I've yet to have a class that
: > discussed issues of this sort.  The only place on campus where these issues
: > were discussed was in the office of the student chapter of the ACM.  (This
: > was the site of many an informative bull session between undergrads, grads,
: > and the occasional faculty advisor.)

:   Quality and thoroughness of commenting was 20% of my grade in the first 
: two (undergraduate) courses I took, and 10% in the last course I took.  
: Needless to say I took to commenting code pretty quickly.

: --
: James Robinson            "Because we are returning a copy for postfix ++ 
: james-robinson@uiowa.edu  expressions, statements such as (c++)++; won't
: robinson@cs.uiowa.edu     work as expected."            -- Weiskamp & Flamig,
:                                            _The_Complete_C++_Primer_, 2nd ed.




--
***********begin r.s. response**************

	wouldn't it be great to
		grow up,
		not worry about what some teacher
			thinks about your comments,
		and just focus on the code?

	i do that now!

***********end r.s. response****************
Ralph Silverman
z007400b@bcfreenet.seflin.lib.fl.us

Re: Hungarian notation

[Dave Toland]

Keith Whittingham wrote:
| And is absolutely horrible! It serves little purpose especially in the world of
| C++ as we can invent our own data types and attempting to extend the convention
| to include our newly defined types makes the code unreadable.
|
| In addition it makes it difficult to change a int to an unsigned int or to
| a long without updating every occurence of the variable name in the code.

Agreed!  It runs entirely counter to the philosophies of data abstraction and
object-oriented programming.  Instead of concealing the details of data
representation, it emphasizes them and nails them securely in place.

I abhorred the notation when I first encountered it.

On the other hand, it is widely enough used that it's a good idea to know a
little about it.  A good book on Windows programming using the API (I don't
know if the MFC tends to use it) would probably have at least a cursory
description of Hungarian notation.  And in terms of readability (as opposed to
maintenance), the type tags do give some indication of intended use of the
variable, unlike variable names like 'q' or 'temp'.

Hungarian notation evolved to fill a need.  It is an attempt to force programmers
to put meaning into the names of variables.  It works, but the authors made the
unfortunate choice of binding names to the representation as much as to the
usage of the variables.  And for C, it probably is not a "wrong" choice, particularly
when there are functions called without prototype declarations, and functions like
printf that cannot match the argument types to the formatting templates at
compile time.

-- 
We awe Fudd of Bawg. Wesistance is usewess.  Pwepare to be assimiwated.
Dave Toland       Platinum Solutions, Inc.    det@platsol.com

Re: Hungarian notation

[mAg]

In article <3198F30F.2A2@zurich.ibm.com> (Tue, 14 May 1996 13:54:39 -0700), 
wgk@zurich.ibm.com says :
>

>
>And is absolutely horrible! It serves little purpose especially in the world of
>C++ as we can invent our own data types and attempting to extend the convention
>to include our newly defined types makes the code unreadable.

This is comp.lang.c. and apart from that there is nothing horrible. It is, in fact, the 
best thing that has happened to C language.

>
>In addition it makes it difficult to change a int to an unsigned int or to 
>a long without updating every occurence of the variable name in the code.

Which means that the original design was not well thought of...


I write programs using hard-core hungarian and I love it. The hungarian-haters can still 
read my programs by simply refusing to interpret the value by looking at the variable 
name.

Someone raised a question about encapsulation, i.e hungarian killing encapsulation.

Why so?

here are few examples :

typedef struct __ZZ__
{
int iSomething;
char *achSomething;
} ZZ;

ZZ *pZz;

int *pInt;
char *pChar;

Which one of these examples violate encapsulation????


-- 
/* --------------------------------------------------------
                      MAG@ESKIMO.COM
http://www.eskimo.com/~mag/index.html
***********************************************************
To understand recursion one must first understand recursion
***********************************************************
-------------------------------------------------------- */

Re: Hungarian notation

[Mark A Biggar]

Hungarian notation's biggest flaw is that it promotes a massive confusion
between physical and abstract typing.  By embedding the physical type
of an object into its name you violate very principal of information
hiding that ever existed.  Just say NO!.


--
Mark Biggar
mab@wdl.loral.com

Re: Hungarian notation

[slary61]

mab@dst17.wdl.loral.com (Mark A Biggar) wrote:
>
> Hungarian notation's biggest flaw is that it promotes a massive confusion
> between physical and abstract typing.  By embedding the physical type
> of an object into its name you violate very principal of information
> hiding that ever existed.  Just say NO!.

Could you explain this in simple terms.
Perhaps an example.

Thanks.

Scott

Re: Hungarian notation

[Bob Lang 3P21 x3172]

In article <DrqsDo.Eu5@eskimo.com>, mag@eskimo.com (mAg) writes:
> In article <3198F30F.2A2@zurich.ibm.com> (Tue, 14 May 1996 13:54:39 -0700), 
> wgk@zurich.ibm.com says :
> >
> 
> >
> >And is absolutely horrible! It serves little purpose especially in the world of
> >C++ as we can invent our own data types and attempting to extend the convention
> >to include our newly defined types makes the code unreadable.
> 
> This is comp.lang.c. and apart from that there is nothing horrible. It is, in fact, the 
> best thing that has happened to C language.

Which begs the question... What is the best thing that *could* happen
to the C language?  Answers on the back of a 10 pound note please  ;-)

Bob
~    ~~~  ~~~~	    ~~   ~~~  ~~ ~~   ~~  ~~~~~  ~~~~	 __	~~  ~~  ~~~ ~
 ~~~~~~~~~   ~~~~~~~~~~~  ~~~~    ~~~~ ~~~~~  ~~~~     _<Zx\	  _ -/       
     Bob Lang	 ~~~~                                	   ||  _-  -/  	_     
~~~~ lr-lang@csm.uwe.ac.uk ~~~~~~~                        // _- -_ -/_- /    
 ~~~ University of the West Of England	 ~~~~          	 //_- _ - _/- =/     
					~~~~~  ~~~~~~~~ (_-_-_- =_-===_/ ~~~~~
~~~ ~~~~~~~~~~ ~~~~~~  ~~~~~~~~~   ~~~~~~~ ~~~~~~~ ~~~~~~~  ~~~~~  ~~~~~~~ ~~

Re: Hungarian notation

[Peter Seebach]

In article <DrqsDo.Eu5@eskimo.com>, mAg <mag@eskimo.com> wrote:
(This is not kosher; never use _'s at the beginnings of names, unless you
feel like memorizing all of the implementation namespace.)

>typedef struct __ZZ__
>{
>int iSomething;
>char *achSomething;
>} ZZ;

>ZZ *pZz;

>int *pInt;
>char *pChar;

>Which one of these examples violate encapsulation????

The problem is that now, you'll see code like
	pZz->iSomething = 3;
which is telling you that it's an int.  That breaks encapsulation; you only
need to know that it's vaguely arithmetic, and if it's changed to unsigned,
you should neither know nor care.

Fundementally, this sort of pseudo-Hungarian buys you nothing.  The variable
names turn into small, frequently innaccurate comments.  They don't tell
you what you need to know.  If you would use interface, rather than
implementation, to decide prefixes, it would make sense.

Consider:  Years later, you need to change this... You need to use
a function... So ZZ has a member
	int (*pifFoov)(void);
which is always set roughly correctly, and we go to
	#define iSomething (*(pifFoov)())
or something similar.  (I know, this isn't precisely right.)

Suddenly, the name is a blatant lie.

How about this:  Notate the following declaration correctly:
	FILE *Foo;

... Hmm.  Maybe it's "pst".  Nope, FILE may not be a struct.  Maybe it's
"pch".  Nope, file may not be a char, even though FILE * is often really
a pointer to char.  Sometimes, it's a pointer to an int.  Sometimes, it's
really a pointer containing a converted int, and will never actually be
used as a pointer.

Any naming convention that tries to tell you the internals of an abstract
is fundementally, and completely, broken.

-s
-- 
Peter Seebach - seebs@solon.com - Copyright 1996 Peter Seebach.
Unix/C Wizard - send mail for help, or send money for consulting!
Unsolicited email is not welcome, and will be billed for at consulting rates.
The *other* C FAQ - http://www.solon.com/~seebs/c/c-iaq.html

Re: Hungarian notation

[Steve Willer]

seebs@solutions.solon.com (Peter Seebach) wrote:

>The problem is that now, you'll see code like
>	pZz->iSomething = 3;

>Consider:  Years later, you need to change this... You need to use
>a function... So ZZ has a member
>	int (*pifFoov)(void);
>which is always set roughly correctly, and we go to
>	#define iSomething (*(pifFoov)())
>or something similar.  (I know, this isn't precisely right.)
>Suddenly, the name is a blatant lie.

Of course it is. So don't do that. If you really need to change the
variable type, you can always do a search-and-replace. With my code, my
HN prefixes are of fairly low detail and the names are usually
descriptive (and unique), so on the rare times when I might change the
type of a member, I just do a search and replace with no problems.

Besides, let's say for the sake of argument that you're not using HN:

  myZ->Something = 3;

First of all, I'll never remember that myZ is a pointer and Something is
an int. I can't rely on my memory and I certainly can't rely on some
other maintainer's ability to memorize my code.

But that aside, what if you do need to change it to a function? How can
you possibly avoid editing the calling code (unless you used that
#define hack, which isn't even an option)? At the very minimum, you'd
have to change it to

  myZ->Something() = 3;

or

  myZ->Something(3);

Either way, you have to change existing code, so I don't see the
disadvantages of having HN in it already.

The reason this doesn't bother me at all is that I don't use data
members very often. At least with C++, my language, you're much better
off to design your classes based on actions and queries, rather than
direct data-exchange. The consequence of this is that member-variables
aren't generally public.

>How about this:  Notate the following declaration correctly:
>	FILE *Foo;
>
>... Hmm.  Maybe it's "pst".  Nope, FILE may not be a struct.  Maybe it's
>"pch".  Nope, file may not be a char, even though FILE * is often really
>a pointer to char.  

???? You're kidding, right? "FILE" is the struct used by the stdio
functions. How can any function get a descriptor number from an array of
chars?

That issue aside...I would use the prefix "pf", as in "pointer to file".
So my declaration would perhaps be:

    FILE *pfFoo;

Seems pretty clear to me.

Re: Hungarian notation

[Richard A. O'Keefe]

willer@carolian.com (Steve Willer) writes:
>Besides, let's say for the sake of argument that you're not using HN:

>  myZ->Something = 3;

>First of all, I'll never remember that myZ is a pointer and Something is
>an int. I can't rely on my memory and I certainly can't rely on some
>other maintainer's ability to memorize my code.

But you _can_ rely on the compiler...

>But that aside, what if you do need to change it to a function?

Well, that's a problem with C++, not a benefit of (non-H)N.

>How can
>you possibly avoid editing the calling code (unless you used that
>#define hack, which isn't even an option)? At the very minimum, you'd
>have to change it to

>  myZ->Something() = 3;

>or

>  myZ->Something(3);

How many people remember what a "selector" is in Alphard?
Can anyone explain to me why Ada doesn't have them (function().all isn't
quite the same thing; selectors are usefully restricted).

In Lisp, it's simply a matter of changing
	(setf (zed-something my-zed) 3)
to
	(setf (zed-something my-zed) 3)

No, there is no typo.

>Either way, you have to change existing code, so I don't see the
>disadvantages of having HN in it already.

I wonder why Lisp programmers have never felt the need for HN?

>???? You're kidding, right? "FILE" is the struct used by the stdio
>functions. How can any function get a descriptor number from an array of
>chars?

If you don't know the answer, you don't yet know C.

>That issue aside...I would use the prefix "pf", as in "pointer to file".
>So my declaration would perhaps be:

>    FILE *pfFoo;

>Seems pretty clear to me.

And how gave you the exclusive rights to "f"?  What about the other
poor schmuck in your project who needs pointers to floats?

The rather interesting thing here is that the C stdio interface has
a design flaw:  the abstract data type C programmers really need to
deal with is (FILE*) not (FILE).  The only reason that it's useful
to know if there's a pointer in there is so that you can compare it
with NULL.  

	typedef FILE* Stdio_Stream;
	...
	Stdio_Stream log_stream;

is a bit clearer than "pfFoo".
-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

Re: Hungarian notation

[Bob Rodgers]

ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe) wrote:
>willer@carolian.com (Steve Willer) writes:
>>Besides, let's say for the sake of argument that you're not using HN:
[...]
>Well, that's a problem with C++, not a benefit of (non-H)N.
[..]

>I wonder why Lisp programmers have never felt the need for HN?

OK, so your point is, C++ sucks.  Well, that's fine, but it's not
constructive or relevant to HN: HN attempts to resolve some of the
most common errors made by C/C++ programmers.  That HN is *also* a
good argument for not using C++, hey, that's nice, but it doesn't
speak to the merits (or lack of) when using HN in C++.

>Fifty years of programming language research, and we end up with C++ ???

Nope, commercial developers end up with C++.  The adventurous are
toying with Portable GCed C++ With Really Awful Window Library (aka
"Java").

The Smalltalk and Lisp programmers end up happy, with OO pruism, demos
and small custom apps for which performance is not in the design
criteria. 

If everyone could use Eiffel (my favorite) or Smalltalk or Lisp,
everyone would. Unfortunately, some of us live in reality.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
http://www.wam.umd.edu/~rsrodger                     homepage & gallery
http://www.wam.umd.edu/~rsrodger/project.htm       rsrodger@wam.umd.edu    

Re: Hungarian notation

[Bob Kitzberger]

Bob Rodgers (rsrodger@wam.umd.edu) wrote:

: OK, so your point is, C++ sucks.  Well, that's fine, but it's not
: constructive or relevant to HN: HN attempts to resolve some of the
: most common errors made by C/C++ programmers.

So, can we get this discussion off of every other newsgroup?

[It is entertaining to see the warts of the C family discussed,
I'll admit, but this particular wart is losing it's entertainment
value.]

--
Bob Kitzberger	      Rational Software Corporation       rlk@rational.com
http://www.rational.com http://www.rational.com/pst/products/testmate.html

Re: Hungarian notation

[Train]

In article <4o19k3$o4b@goanna.cs.rmit.EDU.AU>, 
ok@goanna.cs.rmit.EDU.AU says...
<big snip>
hI rarely comment, but ....
I have been teaching for over 30 years and programming since 1960. 
During 
that time I've seen a lot of code an d blessed/cursed others depending 
on how
easy it was to understand the code. The Micro$loth conventions have 
made
it extremely difficult to pick up a snippet of code and understand 
what's going
on -- unless you are part of that team (maybe 1000 programmers?). 
How
else would they coordinate?
At IBM in the early '60s we had the same problem and "rules" were 
develeped to handle it. One I remember was that 75% of all code 
must have comments. This lead to lines of code saying ST R4,7 
(figure it out) with a comment of "Store 7 in register 4." As you can 
imagine, 75% comments didn't help a great deal.
I've seen all kinds of standards and been part of writing horrible ones 
myself that dictate where indentation will be, how structures are to be 
used, etc. but the end result is: if the coder intends to be clear and 
communicate it really doesn't matter what standards he/she uses, the 
code will be clear.
My students (college and commercially) always start out coding away 
before any design, no comments, and no outlining structure. As they 
have problems I gently (usually) point out that I can't find the end of a 
Select (Switch, or whatever) because they don't line up, I make 
changes to make life easier and help them. You don't really have to 
tell folks not to spill hot coffee all over themselves --- they do it once 
and then they start avoiding it.
I'd like to feel that whatever sloppy code you give me I can figure it 
out, but I am getting old and tired and less likely to take the time and 
comment the mental energy to plow through really bad layout, 
naming, useage, etc. So now I only help when I must or get paid to 
do it.
There ... now I feel better.

Re: Hungarian notation

[jeffos2]

In <4o1ilm$1b0@news.enter.net>, garyl@enter.net (Train) writes:
>In article <4o19k3$o4b@goanna.cs.rmit.EDU.AU>,
>ok@goanna.cs.rmit.EDU.AU says...
><big snip>
>hI rarely comment, but ....
>I have been teaching for over 30 years and programming since 1960.
>During
>that time I've seen a lot of code an d blessed/cursed others depending
>on how
>easy it was to understand the code. The Micro$loth conventions have
>made
>it extremely difficult to pick up a snippet of code and understand
>what's going
>on -- unless you are part of that team (maybe 1000 programmers?).
>How
>else would they coordinate?
>At IBM in the early '60s we had the same problem and "rules" were
>develeped to handle it. One I remember was that 75% of all code
>must have comments. This lead to lines of code saying ST R4,7
>(figure it out) with a comment of "Store 7 in register 4." As you can
>*snip*

Ahh, now I see why OS/360 was soooo buggy.:-)  Storing the *contents* of R4
at location 7 probably isn't exactly what you wanted to do here. Perhaps
something like:
   LA R4,7  Load R4 with 7

But seriously, I am in complete agreement with the point of your post that
blindly adhering to rules does nothing to improve the code quality.

-----
Jeffery Swagger
"IBM has customers to debug the code for them"

Re: Hungarian notation

[Robert Dewar]

Richard O'Keefe said

"Can anyone explain to me why Ada doesn't have them (function().all isn't
quite the same thing; selectors are usefully restricted)."

If one took all the features that might be added to Ada and applied the
following rule:

"Any feature shall be put in, unless there is a sound technical argument
 that shows that the feature is undesirable"

then Ada would get to be a *really* big argument. In fact early on in the
Ada 95 design, the advocates of more functionality often tried to impose
this rule. The point is that if you only apply this narrow criterion, then
you miss the more important goal of keeping the language as small and simple
as possible, consistent with providing needed functionality.

So Richard, the burden is on you to argue that this feature is vital, not
on others to argue that it is not useful.

One useful viewpoint that I have tried to emphasize in the past is the
following:

  Every feature added to a language damages the language by increasing its
  size (and therefore at least the perceived complexity, if not the actual
  complexity).

  Any new feature added must provide enough benefit to at least offset
  this damage, and in practice must provide a net positive benefit.

If you don't apply this kind of principle, then you quickly find the
language gets full of marginal features.

Richard, my specific answer to your question is simple. This feature simply
would not provide sufficient increase in expressive power to warrant the
additional complexity.

If you want to argue otherwise, give some convincing examples of things
that can be done using selectors and not simply otherwise.

Re: Hungarian notation

[Richard A. O'Keefe]

>Richard O'Keefe said

>"Can anyone explain to me why Ada doesn't have 
	Alphard-style selectors
>(function().all isn't quite the same thing; selectors are usefully
>restricted)."

dewar@cs.nyu.edu (Robert Dewar) writes:

>If one took all the features that might be added to Ada and applied the
>following rule:

>"Any feature shall be put in, unless there is a sound technical argument
> that shows that the feature is undesirable"

Yes, yes, of course.  Understood.  Misses the point, of course.

What I am trying to ask is not "why haven't selectors been _added_",
but "why were they left out of the original design"?

Some of the major constructs in Ada are
	- variables		=> selectors (not provided)
	- expressions		=> functions
	- statements		=> procedures
	- blocks		=> packages
One of the design goals of Ada was referential transparency,
and selectors are one means to that end.  The claim that you can
replace an array by a function, often trotted out to explain why
Ada arrays use () instead of Algol/Pascal/C [] (sometimes by me!)
isn't really true, because you can assign to
	f(x)
only when f is an array.

Perhaps I phrase my question infelicitously, but I do feel that Deware
has given it the worst possible interpretation.

What I would like to know is
 - here is a syntactically simple concept
 - which is also simple to implement (I'm putting it in a compiler
   for another language, which will probably never see the light of
   day for other reasons entirely)
 - which had prior art
 - which would have made referential transparency something 
   more than a slogan
*
   so was the omission of this construct accidental or deliberate (in fact,
   I strongly suspect "accidental") and if deliberate, does anyone know
   what the arguments for and against were.

With Ada 95, as with other revisions, "less is more" is a compelling
practical argument.  No matter how desirable a feature may be (and I
could name several I would like) a feature whose inclusion postpones
the delivery of the standard and the provision of higher ranked
features should not be included.  So what else is new?

>So Richard, the burden is on you to argue that this feature is vital, not
>on others to argue that it is not useful.

There is no such burden on me, because I wasn't _demanding_ the feature,
only asking why it was left out.  I think my major question is whether
it was accidental or deliberate.

Please remember that I am a *friend* of Ada (I think anyone who has
seriously tried to use C to develop reliable programs *has* to become
a friend of Ada fairly rapidly) and I am unlikely to attack it, so if
you think I am attacking Ada or the people who developed it, you know
you are misunderstanding me.

-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

Re: Hungarian notation

[Robert Dewar]

Hungarian notation is certainly a remarkable demonstration of how few people
have learned and understood data abstraction. What's most interesting is
how difficult it is for its advocates to see this point, but I suppose that
is not surprising. If you never understood what abstraction is about, then
of course adopting a notation that destroys it will not concern you.

Even the examples that are produced continually reinforce the point that
HN advocates miss the whole point of abstraction.

For example, Steve Willer wrote:

>  myZ->Something = 3;
>
>First of all, I'll never remember that myZ is a pointer and Something is
>an int. I can't rely on my memory and I certainly can't rely on some
>other maintainer's ability to memorize my code.

What ON EARTH is that "3" doing in the code? It is absolutely elementary
that bogus untyped, unnamed constants of this type do not belong in properly
written code, but I am sure that this point also escapes HN advocates.

It is truly remarkable that people would work with a language like C, and
decide that the one problem with the language was that it provides too
much data abstraction (in the form of abstract variable names), and that
even this much abstraction is anathema and must be system
atically eliinated.

Re: Hungarian notation

[slary61]

dewar@cs.nyu.edu (Robert Dewar) wrote:
> Hungarian notation is certainly a remarkable demonstration of how few people
> have learned and understood data abstraction. What's most interesting is
> how difficult it is for its advocates to see this point, but I suppose that
> is not surprising. If you never understood what abstraction is about, then
> of course adopting a notation that destroys it will not concern you.

Perhaps Bill Gates will be contacting you for that explanation.
Although the examples you cite support your opinion, the bottom
line is that some of the largest software developers in the world
insist on code using Hungarian Notation.  

Why?

Re: Hungarian notation

[Ian Ward]

dewar@cs.nyu.edu (Robert Dewar) wrote:
> Hungarian notation is certainly a remarkable demonstration of how few people
> have learned and understood data abstraction. What's most interesting is
> how difficult it is for its advocates to see this point, but I suppose that
> is not surprising. If you never understood what abstraction is about, then
> of course adopting a notation that destroys it will not concern you.

slary61@maine.maine.edu () wrote:
> Perhaps Bill Gates will be contacting you for that explanation.
> Although the examples you cite support your opinion, the bottom
> line is that some of the largest software developers in the world
> insist on code using Hungarian Notation.  

> Why?

Ben Elton, and others in 'Blackadder II - The Elizabethan Sitcom' Wrote:

Size is no guarantee of quality Baldrick, a horse is a magnificently
endowed animal, but one could hardly call it a sensitive lover.


---
Ian Ward's opinions only : ian@rsd.bel.alcatel.be
Hmm! Hmmm! HMMM! ... it's, er "burgled" Mr. President.

Re: Hungarian notation

[Jeff Dege]

On 24 May 1996 02:02:38 GMT, slary61@maine.maine.edu wrote:
: 
: Perhaps Bill Gates will be contacting you for that explanation.
: Although the examples you cite support your opinion, the bottom
: line is that some of the largest software developers in the world
: insist on code using Hungarian Notation.  
: 
: Why?

Because it looks good to managers who are five layers above anyone who's
touched a line of code in the last 15 years.

-- 
  Friendship is born at that moment when one person says to another:
  "What!  You, too?  Thought I was the only one."
                                             -C.S. Lewis

Re: Hungarian notation

[Dave Toland]

slary61@maine.maine.edu wrote:
| dewar@cs.nyu.edu (Robert Dewar) wrote:
| > Hungarian notation is certainly a remarkable demonstration of how few people
| > have learned and understood data abstraction. What's most interesting is
| > how difficult it is for its advocates to see this point, but I suppose that
| > is not surprising. If you never understood what abstraction is about, then
| > of course adopting a notation that destroys it will not concern you.
| 
| Perhaps Bill Gates will be contacting you for that explanation.
| Although the examples you cite support your opinion, the bottom
| line is that some of the largest software developers in the world
| insist on code using Hungarian Notation.
| 
| Why?

Biggest or most doesn't necessarily mean correct.  Hungarian notation has some
advantages, but keep in mind it was developed for C, not C++.  C is a procedural
language, and programs written in it have long been plagued by problems with
mismatches of fundamental data types.  The addition of function prototypes to
the language did much to ameliorate the problem for call interfaces, except for
functions like printf for which compile time checking is not possible *in the
general case* (yes, I know gcc can check printf calls, but only because the compiler
has special knowledge of that runtime routine).  And prototypes can only diagnose
mismatches for invariant argument lists if they are consistently used.  ANSI C
only requires prototypes for variable argument list functions, and in fact a large
body of code cannot use prototypes without tedious macro magic because it must
compile on platforms for which ANSI compilers are not or were not available.
This is where Hungarian notation can help compensate for the failures of the
language.

But C++ is an object oriented language.  Despite its ancestry, its philosophy is
completely different than that of C.  One of the key principles is to hide the
implementation details of the data and to deal instead with the data's abstract
properties.  The very *last* thing you want to do in that paradigm is name your
variables in a way that emphasizes their underlying implementation.

As for me, I've been practicing data abstraction in my C coding for over ten years,
so I've held a certain distaste for Hungarian notation for all that time as well.
I am very aware of the shortcomings of C in terms of type checking, but rather than
constraining variable names, I have favored instead a liberal use of typedefs to
form abstract data types.  I still need to know the underlying types for some
purposes, such as displaying with the printf family, but I try to encapsulate
the code that knows the internal format as much as possible.  I try to minimize
the lifetime and scope of variables, and the longer the lifetime, the more careful
I am in the naming of the variable.  So "i" is an appropriate name for a variable
used an an index for a 3-line iteration, and "CurrentSourceFileInfo" is an
appropriate name for a global structure (if it really must be global) used for
all operations on the source file presently open.

Imposing arbitrary rules results in code every bit as opaque as without the rules.
Teaching good judgement results in maintainable code.  Informed peer review of
code can point out poor name selection and treat it as the defect that it is.

-- 
I protest!  I am *NOT* a Merry Man!
Dave Toland       Platinum Solutions, Inc.    det@platsol.com

Re: Hungarian notation

[Jerry Kuch]

In article <4o35bu$ut8@sol.caps.maine.edu>,  <slary61@maine.maine.edu> wrote:
>dewar@cs.nyu.edu (Robert Dewar) wrote:
>> Hungarian notation is certainly a remarkable demonstration of how few people
>> have learned and understood data abstraction. What's most interesting is
>> how difficult it is for its advocates to see this point, but I suppose that
>> is not surprising. If you never understood what abstraction is about, then
>> of course adopting a notation that destroys it will not concern you.
>
>Perhaps Bill Gates will be contacting you for that explanation.
>Although the examples you cite support your opinion, the bottom
>line is that some of the largest software developers in the world
>insist on code using Hungarian Notation.  

If you've ever actually set foot at Microsoft, you'd have seen that
there are many people there who elect not to use Hungarian notation
and that among those who do there is a fairly broad mixture of
feelings about it.  The vacuous "appeal to authority" method of
argument doesn't at all address the original posters comments about
how Hungarian notation can in a sense undermine the principles of data
abstraction.  To say that "some of the largest software developers in
the world insist on X" and that as a result of this X is somehow good
is as fatuous as saying that "because politician Y is president he
must be the best at being president and every presidential decision he
makes is going to be right."

This brings to mind something that a lot of people don't get.  Programming
is an evolving subject that moves with both changes in technology and the whims
of its practitioners.  Although there are some ideas that are timeless 
such as "comment your code intelligibly," there are other methodologies
that are introduced to solve a specific problem but that over time can
come to lose their usefuless as languages, tools, standards and programming
paradigms change.  Hungarian notation in the form usually bickered over in
this group may have been a good solution for those working in weakly
typed languages with comparatively spartan support for encapsulation and
information hiding, but in environments with extensive support of these
features and polymorphism, it buys much less at the high level.  Perhaps
in the most deeply buried private members of objects, where the data being
handled is being manipulated in a fairly raw and unstructured, close 
to the hardwarze form, this flavor of Hungarian has a role for making
sure that ours arrays, pointers and bit fields don't get mixed up in our
minds.  In levels of code that manipulate comparatively large and complicated
objects, the final production releases of such code should be focussed on
the defined semantics for the objects and methods rather than on the low
level details of their implementation which, from that level of abstraction,
are probably best hidden.

In programming as in anything, dogma breeds inflexible armies of luddites.
What works well should be used, but one eye should always be kept on the
outside world and how it can sneak up and render the familiar rituals
obsolete.

-- 
  Jerry Kuch  EMail:    gdkuch@mercator.math.uwaterloo.ca, NeXTMail welcome.
  IMPORTANT NEWS: Scripts for "Godzilla Vs. Desutoroia" had envisaged
  the monster's main target as the 1996 World City Expo in Tokyo
  but the idea fell through when Gov. Yukio Aoshima cancelled the event.

Re: Hungarian notation

[Jos A. Horsmeier]

In article <4o35bu$ut8@sol.caps.maine.edu>, slary61@maine.maine.edu wrote:
|dewar@cs.nyu.edu (Robert Dewar) wrote:

|> Hungarian notation is certainly a remarkable demonstration of how few
|> people have learned and understood data abstraction. What's most 
|> interesting is how difficult it is for its advocates to see this point,
|> but I suppose that is not surprising. If you never understood what 
|> abstraction is about, then of course adopting a notation that destroys it 
|> will not concern you.

|Perhaps Bill Gates will be contacting you for that explanation.
|Although the examples you cite support your opinion, the bottom
|line is that some of the largest software developers in the world
|insist on code using Hungarian Notation.  
|
|Why?

I don't know the answer to that question, but your last remark made me
wonder: do these 'large software developers' produce better code using
this Hungarian notation? With 'better' I mean 'more efficient', 'more
readable', 'more maintainable' ...

IMHO Hungarian notation is just a bunch of hulla baloo; it doesn't add
anything to the textual representation of the semantics of a piece of
code, i.e. it doesn't make things more readable. While I do agree that
people find:

'All humans are mortal; Aristotle is human; so Aristotle is mortal.'

more readable than:

A(x): { h(x) -> m(x) } , h(a) --> m(a)

I don't think that:

'All p_lt_humans are prop_mortal' lt_Aristotle is lt_human; so lt_Aristotle
is prop_mortal',

where 'p_' stands for plural, 'lt_' denotes a living thing and 'prop_' is
a property, adds much clarity to the understanding of what was actually
said in the first (unreadable?) line ...

But this is all IMHO of course; if people want to use HN, I can't blame
them. All I beg for is, that they should apply it consistently, so I would 
be able to strip all those prefixes off using a simple awk script or even
using sed ... ;-)

kind regards,

Jos aka jos@and.nl

-- 
Qgi nicws nt swaj ri rgw eufgr>

Re: Hungarian notation

[Richard Riehle]

The thread on the captioned topic has been amusing for its passion if not
for its edification.   So far, I have seen no one cite the origins of
Hungarian notation.  It is not, as some have suggested, the product of an
academic enviornment.

The Hungarian notation, as practiced at Microsoft, actually began as a
convention in a programming group managed by Charles Simyoni, a very
fine programmer who was born in Hungary.  Hence, Hungarian notation.

The convention was appropriate for creating large self-documenting C
programs.  As most of us know, C does not lend itself to very well to
self-documenting code.

It is not necessary, and probably superfluous, for code writtin C++,
Ada, Eiffel, or Smalltalk.  The only reason for its continued existence
in C++ is the persistence of C code in C++.  Those of us who are fortunate
enough to benefit from minimal intercourse with C++, have no need of this
notation at all.  It is only when we need to directly interface with
routines written in C/C++ that this convention becomes of interest.

In Eiffel and Ada, the bindings to Windows can be designed to use
more meaningful naming conventions, and that is what is happening.
Therefore, Hungarian notation is a quaint artifact of an earlier
programming style, and of interest mostly as an amusing irrelevancy
in the history of software rather than a serious issue for object
oriented programming.

Can we now be done with this?

Richard Riehle

Re: Hungarian notation

[Warren Young]

Richard Riehle <rriehle@nunic.nu.edu> wrote:

>for its edification.   So far, I have seen no one cite the origins of
>Hungarian notation.  It is not, as some have suggested, the product of an
>academic enviornment.

I've cited it, and in fact it is the product of an academic
environment: it was the subject of Simonyi's doctoral thesis.
Granted, it did spread [only?] because of his influence at Microsoft
(by way of Petzold, and later MFC).

= Warren -- http://www.cyberport.com/~tangent

Re: Hungarian notation

[Eva]

Richard Riehle wrote:
> 
> 
> The Hungarian notation, as practiced at Microsoft, actually began as a
> convention in a programming group managed by Charles Simyoni, a very
> fine programmer who was born in Hungary.  Hence, Hungarian notation.
>




Just one more thing...thanks for enlightening me about what Hungarians 
had to do with all this.  Otherwise, I agree with Warren.

Re: Hungarian notation

[Paul D. DeRocco]

Jos A. Horsmeier wrote:
> IMHO Hungarian notation is just a bunch of hulla baloo; it doesn't add
> anything to the textual representation of the semantics of a piece of
> code, i.e. it doesn't make things more readable.

Hear, hear!

I don't want to contribute to restarting World War I, but Hungarian 
notation makes things less readable, in my view, because the names are 
so damn long that what ought to fit onto a single line ends up taking 
many lines.

Besides, I like to reserve long descriptive names for functions and 
other things of global scope, and use little one- or two-letter names 
for all formal parameters and locals. That way, if you see something 
like:

    for (i = 0; i < number_of_widgets; i++) ...

you automatically know that i is just a temporary concept that has 
meaning during this particular algorithm, while number_of_widgets is a 
real THING that always exists. And as long as all functions fit on a 
page, and all locals are declared at the top of the function, it's 
pretty easy to glance up to see exactly what i is, if it isn't obvious 
from the context.

I guess I'll never work for Bill Gates.

Besides, I'll bet even Hungarians don't like Hungarian notation!

-- 

Ciao,
Paul D. DeRocco

Re: Hungarian notation

[Norman L. Reitzel]

In article <4o35bu$ut8@sol.caps.maine.edu> slary61@maine.maine.edu writes:
>dewar@cs.nyu.edu (Robert Dewar) wrote:
>> Hungarian notation is certainly a remarkable demonstration of how few people
>> have learned and understood data abstraction. What's most interesting is
>> how difficult it is for its advocates to see this point, but I suppose that
>> is not surprising. If you never understood what abstraction is about, then
>> of course adopting a notation that destroys it will not concern you.
>
>Perhaps Bill Gates will be contacting you for that explanation.
>Although the examples you cite support your opinion, the bottom
>line is that some of the largest software developers in the world
>insist on code using Hungarian Notation.  

That way, they can hire half-talented programmers at half-salaries to 
turn out their TOTALLY mediocre code.

Every single decent product provided by MicroSoft (originator of HN) was 
purchased from somewhere else.  I think they are an excellent counterexample.


-- 
   Norman L. Reitzel, Jr.       |    "When you live beside the graveyard,
   nreitzel@lonestar.utsa.edu   |     you can't cry for every funeral."
   Blue Water Ventures, dba.    |                     Russian Proverb

Re: Hungarian notation

[Matt Kennel]

Norman L. Reitzel (nreitzel@lonestar.jpl.utsa.edu) wrote:
: Every single decent product provided by MicroSoft (originator of HN) was 
: purchased from somewhere else. 

Except one.  The first version of Macintosh Excel.  Which really led to
the rest of their success, as all products, including Windows (which
started out as nothign but life-support for Excel on PC's), were patterned
after that one. 

Re: Hungarian notation

[Richard A. O'Keefe]

slary61@maine.maine.edu writes:

>Perhaps Bill Gates will be contacting you for that explanation.
>Although the examples you cite support your opinion, the bottom
>line is that some of the largest software developers in the world
>insist on code using Hungarian Notation.  

>Why?

This argument does not have a valid form.
More people speak Chinese than any other family of languages.
So should we all drop English and switch to Mandarin?

Come to think of it, should we be interested in the practices
of the *biggest* developers or of the *best*?

Frankly, I have come to the end of my tether.
I am *sick* of programs that don't work.
I am *sick* of operating systems that crash.
I am *sick* of word processors that hang my machine.
I am *sick* of hypercomplex interfaces with pathetic documentation.
I am *sick* of file transfer programs that scramble student files.
I am *sick* of oh well you get the idea.

I am nearly as fed up with Apple as I am with Micro$oft.

I want to learn from the people who routinely produce programs that work.

-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

Re: Hungarian notation

[Jay Martin]

ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe) writes:

>Frankly, I have come to the end of my tether.
>I am *sick* of programs that don't work.
>I am *sick* of operating systems that crash.
>I am *sick* of word processors that hang my machine.
>I am *sick* of hypercomplex interfaces with pathetic documentation.
>I am *sick* of file transfer programs that scramble student files.
>I am *sick* of oh well you get the idea.

>I am nearly as fed up with Apple as I am with Micro$oft.

>I want to learn from the people who routinely produce programs that work.

If you think virtually anyone in academic Computer Science really
gives a rats ass about the above (software design and implementation),
boy are you in the wrong field!

Re: Hungarian notation

[Richard A. O'Keefe]

jmartin@cs.ucla.edu (Jay Martin) writes:

>ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe) writes:

>>Frankly, I have come to the end of my tether.
>>I am *sick* of programs that don't work.
>>I am *sick* of operating systems that crash.
>>I am *sick* of word processors that hang my machine.
>>I am *sick* of hypercomplex interfaces with pathetic documentation.
>>I am *sick* of file transfer programs that scramble student files.
>>I am *sick* of oh well you get the idea.

>>I am nearly as fed up with Apple as I am with Micro$oft.

>>I want to learn from the people who routinely produce programs that work.

>If you think virtually anyone in academic Computer Science really
>gives a rats ass about the above (software design and implementation),
>boy are you in the wrong field!

When it first came on the stage, RMIT was "The Melbourne Working Men's
College".  Nowadays it is a fully fledged university, but the basic
ethos is still "we are here to educate people to be effective at their
job".  Tertiary education here is divided (to grossly over-simplify)
into "the TAFE sector" (training) and "the HECS sector" (education).
In this department, we try to provide *education*, not (or not just)
*training*.  (There is also an RMIT TAFE division which provides
training.)  But it is supposed to be education that will actually help
people do a better job.

We have a long way to go.  Teaching is *extremely* hard.  But we try.
Our graduates have a pretty good chance of getting a job in the field
they studied.  The Federal government here is talking about 10-12%
cuts to higher education next year.  You can bet your bottom dollar
that we care *passionately* about the reputation our graduates earn
for us.  And so we care passionately about trying to teach them how
to work well in a real programming environment.

In my "home" university, the University of Auckland in New Zealand,
I know that the staff in the CS department there, like here, care about
research, but also care deeply that their students actually have a
reasonable level of competence.  And for what it's worth, I know that
my friends at the University of Melbourne also care about this.

In an environment where doctrinaire economic irrationalists play
Sweeney Todd, where more students go looking for jobs after their
first degree than continue with further study, and where you have
only to read comp.risks or Software Engineering Notes to see how
much suffering is caused by bad programs, any CS academic has to
care passionately about software design and implementation.  If
we don't, then we will soon have to look for new jobs, and who then
will want us?

In an environment where native speakers of English are not only not
taught to spell, but can enter university not knowing the difference
between "as such" and "such as", and writing sentences like "I would
suggest consulting to a good book", our ability to teach students to
write good comments is obviously limited.

Anyone who actually has to *mark* student programs wants them to write
well, with appropriate comments.

If there is anyone at all in academic computer science who doesn't
care about software design and implementation, perhaps there may be
a few people with established reputations who don't come into contact
with many undergraduate students and don't actually use computers much
themselves.

Mind you, there are people who *care* who don't know what good code *is*.
I've just been looking at a C textbook where the authors go out of their
way to tell their readers to use names like "quarter_t", which names are
of course reserved in ANSI C.  At least they thought about naming, even
if they know little about ANSI C.

-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

Re: Hungarian notation

[Michael Feldman]

In article <4offnb$1gbu@uni.library.ucla.edu>,
Jay Martin <jmartin@cs.ucla.edu> wrote:

>If you think virtually anyone in academic Computer Science really
>gives a rats ass about the above (software design and implementation),
>boy are you in the wrong field!

This is definitely flame bait, Jay. You are tarring with a rather broad
brush here. Maybe in _your_ university they don't care.

Mike Feldman
------------------------------------------------------------------------
Michael B. Feldman -  chair, SIGAda Education Working Group
Professor, Dept. of Electrical Engineering and Computer Science
The George Washington University -  Washington, DC 20052 USA
202-994-5919 (voice) - 202-994-0227 (fax) 
http://www.seas.gwu.edu/faculty/mfeldman
------------------------------------------------------------------------
       Pork is all that money the government gives the other guys.
------------------------------------------------------------------------
Ada on the WWW: http://lglwww.epfl.ch/Ada/ or http://info.acm.org/sigada/
------------------------------------------------------------------------

Re: Hungarian notation

[AJ Musgrove]

slary61@maine.maine.edu wrote:
: dewar@cs.nyu.edu (Robert Dewar) wrote:
: > Hungarian notation is certainly a remarkable demonstration of how few people
: > have learned and understood data abstraction. What's most interesting is
: > how difficult it is for its advocates to see this point, but I suppose that
: > is not surprising. If you never understood what abstraction is about, then
: > of course adopting a notation that destroys it will not concern you.

: Perhaps Bill Gates will be contacting you for that explanation.
: Although the examples you cite support your opinion, the bottom
: line is that some of the largest software developers in the world
: insist on code using Hungarian Notation.  

: Why?  
  ^^^^
Considering how bugy Micro$loths code is, I'm wondering why myself. It
isn't helping them. I use NT and mostly Microsh*t apps at work (not
by choice), and all day, I have to ask myself, why did it do that?
I actually program on a Sun system, where I don't have to
constanly ask that. If my NT workstation was anything more than a 
big X-Term/E-Mail Client/Work Processor, I don't know how I would
manage. 

I tried HN for a while. It mangled code and made it difficult to maintain
ALOT more than it was helped. Besides, IMHO, you can tell from code
what the var is, and, if not, just look how the damn thing
is declared.

--
AJ Musgrove

----------------------------------------------------------------
My opinions are just that
----------------------------------------------------------------

Re: Hungarian notation

[Ralph Silverman]

Richard A. O'Keefe (ok@goanna.cs.rmit.EDU.AU) wrote:
: slary61@maine.maine.edu writes:

: >Perhaps Bill Gates will be contacting you for that explanation.
: >Although the examples you cite support your opinion, the bottom
: >line is that some of the largest software developers in the world
: >insist on code using Hungarian Notation.  

: >Why?

: This argument does not have a valid form.
: More people speak Chinese than any other family of languages.
: So should we all drop English and switch to Mandarin?

: Come to think of it, should we be interested in the practices
: of the *biggest* developers or of the *best*?

: Frankly, I have come to the end of my tether.
: I am *sick* of programs that don't work.
: I am *sick* of operating systems that crash.
: I am *sick* of word processors that hang my machine.
: I am *sick* of hypercomplex interfaces with pathetic documentation.
: I am *sick* of file transfer programs that scramble student files.
: I am *sick* of oh well you get the idea.

: I am nearly as fed up with Apple as I am with Micro$oft.

: I want to learn from the people who routinely produce programs that work.

: -- 
: Fifty years of programming language research, and we end up with C++ ???
: Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

--
**********begin r.s. response************

	that is an easy one!
	i can answer that!!!

	i would suggest a
		time machine
	go back to
		bell telephone laboratories
	in,  oh,  1978!

	(btw) if you are going,
		kindly let me know...
	i might come along!

**********end r.s. response**************
Ralph Silverman
z007400b@bcfreenet.seflin.lib.fl.us

Re: Hungarian notation

[Ralph Silverman]

Jeff Dege (jdege@winternet.com) wrote:
: On 24 May 1996 02:02:38 GMT, slary61@maine.maine.edu wrote:
: : 
: : Perhaps Bill Gates will be contacting you for that explanation.
: : Although the examples you cite support your opinion, the bottom
: : line is that some of the largest software developers in the world
: : insist on code using Hungarian Notation.  
: : 
: : Why?

: Because it looks good to managers who are five layers above anyone who's
: touched a line of code in the last 15 years.

: -- 
:   Friendship is born at that moment when one person says to another:
:   "What!  You, too?  Thought I was the only one."
:                                              -C.S. Lewis

--
************begin r.s. response************

	also,
	does this not enable
		critics,
		managers,
		commentators
	and
		'superiors'
	generally
	to
		'seem to know'
	what the code is about...
	even when they have no idea
	how such things work?

************end r.s response***************
Ralph Silverman
z007400b@bcfreenet.seflin.lib.fl.us

Re: Hungarian notation

[Steve Willer]

dewar@cs.nyu.edu (Robert Dewar) wrote:

>For example, Steve Willer wrote:
>
>>  myZ->Something = 3;
>>
>>First of all, I'll never remember that myZ is a pointer and Something is
>>an int. I can't rely on my memory and I certainly can't rely on some
>>other maintainer's ability to memorize my code.
>
>What ON EARTH is that "3" doing in the code? 

It is a simple example line of code, set up as a quick illustration of
naming conventions. It is not intended to be an example of wonderful
programming practices.

>It is absolutely elementary
>that bogus untyped, unnamed constants of this type do not belong in properly
>written code, but I am sure that this point also escapes HN advocates.

That's an unfair characterisation. What I have been trying to say is
that I find my own naming convention gives me a useful buffer between my
keyboard and the language's type-checking system (which is imperfect).
It gives me an opportunity to proofread the code _before_ the compiler
sees it.

>It is truly remarkable that people would work with a language like C, and
>decide that the one problem with the language was that it provides too
>much data abstraction (in the form of abstract variable names), and that
>even this much abstraction is anathema and must be system
>atically eliinated.

I certainly never said it provides too much data abstraction. What I'm
saying is if you are using member variables or function arguments, you
need to be aware of certain aspects of the variable or argument so you
don't inadvertently shoot yourself in the foot. Examples are giving a
float to a function that expects an int, giving a pointer to a function
that expects a long, giving a pointer that you own to a function that
expects an auto_ptr. This is not about 100% pure data abstraction; I
think it is clear that that is just not attainable in C or C++. This is,
in fact, about compromise and decisions based on costs vs. benefits.

Re: Hungarian notation

[Peter Seebach]

In article <31a3b322.442404233@sqarc>,
Steve Willer <willer@carolian.com> wrote:
>The reason this doesn't bother me at all is that I don't use data
>members very often. At least with C++, my language, you're much better
>off to design your classes based on actions and queries, rather than
>direct data-exchange. The consequence of this is that member-variables
>aren't generally public.

This is good design in C, also, although the syntax is spelled differently.

>>... Hmm.  Maybe it's "pst".  Nope, FILE may not be a struct.  Maybe it's
>>"pch".  Nope, file may not be a char, even though FILE * is often really
>>a pointer to char.  

>???? You're kidding, right? "FILE" is the struct used by the stdio
>functions. How can any function get a descriptor number from an array of
>chars?

Perhaps it points to a character which holds the value of the descriptor that
implements that file.  Perhaps the character pointed to is the index into a
hidden array of other things.

It's a struct *in some implementations*.  No legitimate code can ever tell,
nor can it make any use of the internals or contents of the struct if it is
one.  It is merely an opaque abstract type.

>That issue aside...I would use the prefix "pf", as in "pointer to file".
>So my declaration would perhaps be:

>    FILE *pfFoo;

>Seems pretty clear to me.

Yes.  You have seen through the false type-safety of encoding low level types,
and found the true path of encoding the meaning, not the implementation.

-s
-- 
Peter Seebach - seebs@solon.com - Copyright 1996 Peter Seebach.
Unix/C Wizard - send mail for help, or send money for consulting!
Unsolicited email is not welcome, and will be billed for at consulting rates.
The *other* C FAQ - http://www.solon.com/~seebs/c/c-iaq.html

Re: Hungarian notation

[Oleg Kagan]

mAg wrote:
> 
> In article <3198F30F.2A2@zurich.ibm.com> (Tue, 14 May 1996 13:54:39 -0700),
> wgk@zurich.ibm.com says :
> >
> 
> >
> >And is absolutely horrible! It serves little purpose especially in the world of
> >C++ as we can invent our own data types and attempting to extend the convention
> >to include our newly defined types makes the code unreadable.
> 
> This is comp.lang.c. and apart from that there is nothing horrible. It is, in fact, the
> best thing that has happened to C language.
> 
> >
> >In addition it makes it difficult to change a int to an unsigned int or to
> >a long without updating every occurence of the variable name in the code.
> 
> Which means that the original design was not well thought of...
> 
> I write programs using hard-core hungarian and I love it. The hungarian-haters can still
> read my programs by simply refusing to interpret the value by looking at the variable
> name.
> 
> Someone raised a question about encapsulation, i.e hungarian killing encapsulation.
> 
> Why so?
> 
> here are few examples :
> 
> typedef struct __ZZ__
> {
> int iSomething;
> char *achSomething;
> } ZZ;
> 
> ZZ *pZz;
> 
> int *pInt;
> char *pChar;
> 
> Which one of these examples violate encapsulation????
> 
> --
> /* --------------------------------------------------------
>                       MAG@ESKIMO.COM
> http://www.eskimo.com/~mag/index.html
> ***********************************************************
> To understand recursion one must first understand recursion
> ***********************************************************
> -------------------------------------------------------- */
 I You want Your code look like nice... so...
to define array of char i use a little bit different notation

char ac_ExampleOfArrayOfChar[]; // :)

Re: Hungarian notation

[Ralph Silverman]

Oleg Kagan (ok@netvision.net.il) wrote:
: mAg wrote:
: > 
: > In article <3198F30F.2A2@zurich.ibm.com> (Tue, 14 May 1996 13:54:39 -0700),
: > wgk@zurich.ibm.com says :
: > >
: > 
: > >
: > >And is absolutely horrible! It serves little purpose especially in the world of
: > >C++ as we can invent our own data types and attempting to extend the convention
: > >to include our newly defined types makes the code unreadable.
: > 
: > This is comp.lang.c. and apart from that there is nothing horrible. It is, in fact, the
: > best thing that has happened to C language.
: > 
: > >
: > >In addition it makes it difficult to change a int to an unsigned int or to
: > >a long without updating every occurence of the variable name in the code.
: > 
: > Which means that the original design was not well thought of...
: > 
: > I write programs using hard-core hungarian and I love it. The hungarian-haters can still
: > read my programs by simply refusing to interpret the value by looking at the variable
: > name.
: > 
: > Someone raised a question about encapsulation, i.e hungarian killing encapsulation.
: > 
: > Why so?
: > 
: > here are few examples :
: > 
: > typedef struct __ZZ__
: > {
: > int iSomething;
: > char *achSomething;
: > } ZZ;
: > 
: > ZZ *pZz;
: > 
: > int *pInt;
: > char *pChar;
: > 
: > Which one of these examples violate encapsulation????
: > 
: > --
: > /* --------------------------------------------------------
: >                       MAG@ESKIMO.COM
: > http://www.eskimo.com/~mag/index.html
: > ***********************************************************
: > To understand recursion one must first understand recursion
: > ***********************************************************
: > -------------------------------------------------------- */
:  I You want Your code look like nice... so...
: to define array of char i use a little bit different notation

: char ac_ExampleOfArrayOfChar[]; // :)

--
**********begin r.s. response***********

	off the cuff response to issue
	of
		altering data types
	in material cited above,
		is unduly casual!

	alteration of data types in
	such,  does not necessarily result
	from vacillation or from
	lack of planning!

**********end r.s. response*************
Ralph Silverman
z007400b@bcfreenet.seflin.lib.fl.us

Re: Hungarian notation

[David Priest]

mcrogerm@stjohn.sju.ac.th (Roger Merritt) writes:
>Franz.Kruse@erno.de (Franz Kruse) wrote:
>>Could someone please post an article describing Hungarian Notation in some detail
>>and giving examples?
>>Thanks,
>
>If you can get the book Code Complete from Microsoft Press (can't
>remember the author) he describes the coding method in detail. It was
>devised by a super-programmer at Microsoft (originally at PARC) named
>Semonyi (if my memory is correct) who was Hungarian.
>
>The book I mentioned is a fairly good one on the methodology of
>designing software, but I thought it was far too long and contained
>far too few code examples.

Code Complete, by Steve McConnell.  If Microsoft only took McConnell's 
programming recommendations to heart, they'd have much less buggy code.  
I, frankly, worship this book: it was to-the-point and backed up many of 
his recommendations with hard-core statistical proof of the efficacy of 
the technique.  Liked it so much that I wrote myself a point-form summary 
of it, to make quick-referencing even that much quicker (and, no, it's 
not available to others; go buy the book yourself).

I also thought Code Complete did a nice job of definitively proving why 
one should not choose C/C++ as a programming language...

Re: Hungarian notation

[The Right Reverend Colin James III]

Stop posting this banal thread, which has nothing to do with Eiffel, to
comp.lang.eiffel.

------------------------------------------------------------------

mcrogerm@stjohn.sju.ac.th (Roger Merritt) posted with deletions:

| Franz.Kruse@erno.de (Franz Kruse) wrote:
| 
| 
| >Could someone please post an article describing Hungarian Notation in some detail
| >and giving examples?
| 
| >Thanks,
| 
| >Franz
| 
| If you can get the book Code Complete from Microsoft Press (can't
| remember the author) he describes the coding method in detail. It was
| devised by a super-programmer at Microsoft (originally at PARC) named
| Semonyi (if my memory is correct) who was Hungarian.
| 
| The idea is that you include information in the name of the variable
| to help you remember the type. So a pointer to a char might be named
| cpCurrent.
| 
| Same thing applies to function names to help you remember the type
| returned.
| 
| The book I mentioned is a fairly good one on the methodology of
| designing software, but I thought it was far too long and contained
| far too few code examples.
| 
| 

Colin James III 
cjames@bod.boss.net
Do not send harassing email to me.

Re: Hungarian notation

[Graham Perkins]

Re: Hungarian notation and CJIIIRR
----------------------------------
> Stop posting this banal thread, which has nothing to do with Eiffel, to
> comp.lang.eiffel.

It most certainly has much to do with Eiffel.  I assert that

  a) Developing good naming schemes is a critical part of 
     any software development project.

  b) Hungarian notation is used in some large projects (eg
     Microsoft products)

  c) Software developers should be aware of software engineering
     techniques used in large products and how applicable they are to
     the particular language/project they are embarking upon.

In particular, point (c) above could include software developers
working with Eiffel.

Re: Hungarian notation
----------------------
A careful reading of chapter 9 in "Code Complete" by Steve McConnell
(published Microsoft press) reveals much good advice.  As it happens,
much of the recommended naming structures (Hungarian and otherwise)
can be dispensed with by Eiffel programmers as they are geared to C
like languages.  But some aspects are entirely relevant.  The intelligent
reader will be able to see how Eiffel automatically supports many of
the goals of Hungarian notation, and how other goals still need to
be addresses.

Bertrand Meyer's book "Reusable Software" also addresses identifier
naming schemes in the chapter on library design.  I thoroughly 
recommend it to all software library designers, Eiffelists or not.

Re: Naming schemes in general
-----------------------------
Some of the issues addressed in "Code Complete" can be bypassed by the
Eiffel or general OO programmer.  For example, metrics published in 
the "Object Oriented Applications" book (eds. Bertrand Meyer & Jean-Marc 
Nerson, pub. Prentice Hall) indicate that most classes are not large
(average 5-14 features, depending on which cluster) and most methods 
are also fairly short (2-13 lines depending on cluster).  Thus it is
probably not worth bothering to distinguish scope, since locals will
only be a few lines away and all other id's will be qualified by their
owner's name anyhow (unless belonging to Current).  There are no
statics or globals in Eiffel, so we don't need codes for them either.

The presence of multiple inheritance is quite relevant, since we can
place our names high up in abstract classes (effectively determining
common names across many descendant classes).  Without working on the
commonalities across low-level concrete classes, the programmer will
miss many opportunities for ancestor delegation or at least ancestral
specification.

> Colin James III
> cjames@bod.boss.net
> Do not send harassing email to me.

According to replies from this address, this user bounces *all* email.

Re: Hungarian notation

[Peter Seebach]

In article <3199C1CB.5187@dmu.ac.uk>, Graham Perkins  <grp@dmu.ac.uk> wrote:
>A careful reading of chapter 9 in "Code Complete" by Steve McConnell
>(published Microsoft press) reveals much good advice.  As it happens,
>much of the recommended naming structures (Hungarian and otherwise)
>can be dispensed with by Eiffel programmers as they are geared to C
>like languages.  But some aspects are entirely relevant.  The intelligent
>reader will be able to see how Eiffel automatically supports many of
>the goals of Hungarian notation, and how other goals still need to
>be addresses.

And the intelligent reader will also note that the system proposed is
actually detrimental to competent C programming, and encourages, even
*enforces*, the kinds of poor practices us poor C programmers are so
disparaged for.

>> Colin James III
>> cjames@bod.boss.net
>> Do not send harassing email to me.

>According to replies from this address, this user bounces *all* email.

Not true, however; at one point, he sent me email, pointing out that a
thread (not dissimilar to this one) had no relation to Eiffel.  Since
the specific post he quoted actually compared Eiffel and C, I felt this
was unfair.  My first response, stating merely that I didn't think it
was atopical, was responded to *with something other than the form letter*.

It was only my 2nd letter, where I pointed out that the quoted material
specifically discussed Eiffel, which got the form letter we all know and
love.

He also sent copies of related material to several postmasters, including
postmaster@xerox.com, despite the fact that none of the correspondance
involved came from or had anything to do with Mother Xerox.

I suppose I must defend him, though, and point out that consistency is
the hobgoblin of little minds.

-s
p.s.: The "consistency" quote was by far the most popular quote among seniors
in the class 3 ahead of me in high school.  At least three of them put it in
the yearbook.  Each, of course, phrased it differently, although they all
attributed it to the same source.
-- 
Peter Seebach - seebs@solon.com - Copyright 1996 Peter Seebach.
Does anyone read these things?  I doubt it, but I've never been sure.
Unsolicited email is not welcome, and will be billed for at consulting rates.
The *other* C FAQ - http://www.solon.com/~seebs/c/c-iaq.html

Re: Hungarian notation

[Pete Becker]

In article <4nckae$1j2@solutions.solon.com>, seebs@solutions.solon.com says...
>
>I suppose I must defend him, though, and point out that consistency is
>the hobgoblin of little minds.
>
>-s
>p.s.: The "consistency" quote was by far the most popular quote among seniors
>in the class 3 ahead of me in high school.  At least three of them put it in
>the yearbook.  Each, of course, phrased it differently, although they all
>attributed it to the same source.

And did they all leave out the critical two words "a foolish" which come before 
the word "consistency" in the original?

Re: Hungarian notation

[James Kanze US/ESC 60/3/141 #40763]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1212 bytes --]


In article <31a3b322.442404233@sqarc> willer@carolian.com (Steve Willer)
writes:

|> >How about this:  Notate the following declaration correctly:
|> >	FILE *Foo;
|> >
|> >... Hmm.  Maybe it's "pst".  Nope, FILE may not be a struct.  Maybe it's
|> >"pch".  Nope, file may not be a char, even though FILE * is often really
|> >a pointer to char.  

|> ???? You're kidding, right? "FILE" is the struct used by the stdio
|> functions. How can any function get a descriptor number from an array of
|> chars?

No.  FILE is whatever the implementation wants it to be.  There is
absolutly nothing wrong with an implementation declaring a FILE as an
integral type (which it then uses as an index into an array of
whatevers); it is probably even a good idea to do so, since it keeps the
programmers honest (and means they don't even have to recompile if I
change some of the internals of my actual descripter).
-- 
James Kanze         Tel.: (+33) 88 14 49 00        email: kanze@gabi-soft.fr
GABI Software, Sarl., 8 rue des Francs-Bourgeois, F-67000 Strasbourg, France
Conseils, �tudes et r�alisations en logiciel orient� objet --
                -- A la recherche d'une activit� dans une region francophone

Re: Hungarian notation

[Brian Rogoff]

ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe) writes:
   >Richard O'Keefe said

   >"Can anyone explain to me why Ada doesn't have 
	   Alphard-style selectors
   >(function().all isn't quite the same thing; selectors are usefully
   >restricted)."

Could you explain what Alphard style selectors are? Thanks.

   What I would like to know is
    - here is a syntactically simple concept
    - which is also simple to implement (I'm putting it in a compiler
      for another language, which will probably never see the light of
      day for other reasons entirely)
    - which had prior art
    - which would have made referential transparency something 
      more than a slogan
   *

Great question. I'd love to know which interesting features were considered 
and rejected during the design of Ada (83 and 95). Iterators existed in CLU, 
which I think predates Ada. I often wonder why this feature, or something like 
it, isn't in Ada.

   >So Richard, the burden is on you to argue that this feature is vital, not
   >on others to argue that it is not useful.

   There is no such burden on me, because I wasn't _demanding_ the feature,
   only asking why it was left out.  I think my major question is whether
   it was accidental or deliberate.

Now that GNAT is out there, maybe we'll see some experimentation with new 
features, and interesting dialects will emerge.

-- Brian

Re: Hungarian notation

[Homonnai Misi]

Roger Merritt (mcrogerm@stjohn.sju.ac.th) wrote:
: Franz.Kruse@erno.de (Franz Kruse) wrote:


: >Could someone please post an article describing Hungarian Notation in some detail
: >and giving examples?

: >Thanks,

: >Franz

: If you can get the book Code Complete from Microsoft Press (can't
: remember the author) he describes the coding method in detail. It was
: devised by a super-programmer at Microsoft (originally at PARC) named
: Semonyi (if my memory is correct) who was Hungarian.

 Simonyi

Mihaly HOMONNAI

Re: Hungarian notation

[James Kanze US/ESC 60/3/141 #40763]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1930 bytes --]


In article <TANMOY.96May17072919@qcd.lanl.gov> tanmoy@qcd.lanl.gov
(Tanmoy Bhattacharya) writes:

|> In article <319B2494.68AB@platsol.com>
|> Dave Toland <det@platsol.com> writes:

|> DT: usage of the variables.  And for C, it probably is not a "wrong"
|> choice, particularly 
|> DT: when there are functions called without prototype declarations,
|> and functions like 
|> DT: printf that cannot match the argument types to the formatting templates at
|> DT: compile time.

|> "cannot" is too strong. The C language clearly allows the compiler to
|> know about standard library functions like printf. In fact at least
|> one free compiler does check the arguments against the formatting
|> directive, and more should do.

This must be an amazingly brillant compiler, since the format strings
are almost always the result of a call to gettext (or its equivalent on
non-Unix systems), which means that they are read from an external file
which generally won't even exist on the machine which is doing the
compiling.  Or does this compiler also know the semantics of gettext,
and simply suppose that the translators won't screw it up.  (Wishful
thinking, of course.  But I guess it really is too much to ask for a
warning along the lines of: ``Warning: the translator who does the
Estonian localization 5 years from now will accidentally change the %d
into a %s.'')

This isn't to say I approve of Hungarian notation, even in C and used
with printf.  Nor to criticize a compiler from generating a warning on
obviously bad code.  Just that this warning won't really be as useful
as one would like in commercial software.
-- 
James Kanze         Tel.: (+33) 88 14 49 00        email: kanze@gabi-soft.fr
GABI Software, Sarl., 8 rue des Francs-Bourgeois, F-67000 Strasbourg, France
Conseils, �tudes et r�alisations en logiciel orient� objet --
                -- A la recherche d'une activit� dans une region francophone

Re: Hungarian notation

[Tom Wheeley]

In article <KANZE.96May20192546@slsvgqt.lts.sel.alcatel.de>
           kanze@lts.sel.alcatel.de "James Kanze US/ESC 60/3/141 #40763" writes:

> 
> |> "cannot" is too strong. The C language clearly allows the compiler to
> |> know about standard library functions like printf. In fact at least
> |> one free compiler does check the arguments against the formatting
> |> directive, and more should do.
> 
> This must be an amazingly brillant compiler, since the format strings
> are almost always the result of a call to gettext (or its equivalent on
> non-Unix systems), which means that they are read from an external file
> which generally won't even exist on the machine which is doing the
> compiling.  Or does this compiler also know the semantics of gettext,

The check is simply based on (AFAICS) a string literal format string
(I cannot think of a good reason why not to use a literal format string, as
you have that much more control over it.)

> and simply suppose that the translators won't screw it up.  (Wishful
> thinking, of course.  But I guess it really is too much to ask for a
> warning along the lines of: ``Warning: the translator who does the
> Estonian localization 5 years from now will accidentally change the %d
> into a %s.'')

Surely the localisation would not involve the changing of types, thus
language specific text can be simply included via %s.  Ok so it may be a
tad slower, but it is a hell of a lot safer.

At least, I *think* that that is what you are talking about.  You would
use printf(s); instead of printf("%s",s); ?  Especially if reading from a
file, I would never make code so easily breakable.

.splitbung
-- 
* TQ 1.0 * The 'Just So Quotes'.
'My Country right or wrong' is like saying 'My Mother drunk or sober.' "
	-- G. K. Chesterton

Re: Hungarian notation

[Steve Willer]

kanze@lts.sel.alcatel.de (James Kanze US/ESC 60/3/141 #40763) wrote:

>This must be an amazingly brillant compiler...

It is. It was written by the FSF people. It's called "gcc". :-) 
In particular, gcc checks the arguments of the printf family against the
formatter string when the -Wall option is on (actually, I'm sure it's a
specific warning, but I always use -Wall).

It only warns with these specific functions; if you declare your own
function that uses varargs and vsprintf, it won't check it. Yes, it's a
hack, but it's a really _nice_ hack.

>This isn't to say I approve of Hungarian notation, even in C and used
>with printf.  Nor to criticize a compiler from generating a warning on
>obviously bad code.  Just that this warning won't really be as useful
>as one would like in commercial software.

You really think so? Perhaps I'm misunderstanding you. A common mistake
around here is to write something like:

printf("The number is %n\n",mynumber);

...which would only crash when the program hits this line of code, and
then only if "mynumber" had a value that made it crash. I can't tell you
how many times we've made this mistake and gcc's caught it (actually, I
could probably guess: maybe 10 over the last year and a half).

Re: Hungarian notation

[James Kanze US/ESC 60/3/141 #40763]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 3606 bytes --]


In article <832631288snz@tsys.demon.co.uk> Tom Wheeley
<tomw@tsys.demon.co.uk> writes:

|> In article <KANZE.96May20192546@slsvgqt.lts.sel.alcatel.de>
|>            kanze@lts.sel.alcatel.de "James Kanze US/ESC 60/3/141 #40763" writes:

|> > 
|> > |> "cannot" is too strong. The C language clearly allows the compiler to
|> > |> know about standard library functions like printf. In fact at least
|> > |> one free compiler does check the arguments against the formatting
|> > |> directive, and more should do.
|> > 
|> > This must be an amazingly brillant compiler, since the format strings
|> > are almost always the result of a call to gettext (or its equivalent on
|> > non-Unix systems), which means that they are read from an external file
|> > which generally won't even exist on the machine which is doing the
|> > compiling.  Or does this compiler also know the semantics of gettext,

|> The check is simply based on (AFAICS) a string literal format string
|> (I cannot think of a good reason why not to use a literal format string, as
|> you have that much more control over it.)

The problem is that the the string must change according to the locale,
and of course, the locale is not known until run-time.

|> > and simply suppose that the translators won't screw it up.  (Wishful
|> > thinking, of course.  But I guess it really is too much to ask for a
|> > warning along the lines of: ``Warning: the translator who does the
|> > Estonian localization 5 years from now will accidentally change the %d
|> > into a %s.'')

|> Surely the localisation would not involve the changing of types, thus
|> language specific text can be simply included via %s.  Ok so it may be a
|> tad slower, but it is a hell of a lot safer.

The localisation *shouldn't* involve changing types.  In reality, the
person typing in the foreign language text may make a mistake.  (In my
experience, this most often happens when using the X/Open extension
with positional parameters.  The types get swapped.)

I've "solved" the problem by using C++, and designing a special
type-safe interface.  But I think you have found the correct solution
for C: do all type conversions using sprintf, and only allow "%s" in
the translatable string.  It should be simple to provide a wrapper for
gettext, which verifies this (and also that the number of %'s is
correct). 

|> At least, I *think* that that is what you are talking about.  You would
|> use printf(s); instead of printf("%s",s); ?  Especially if reading from a
|> file, I would never make code so easily breakable.

It *does* make code easily breakable (although the file is not
generally writable by the user).  I wish I'd thought of your solution,
above, when I was still using C.

More generally, since the results of gettext are so often used as a
format string for printf, wouldn't it be nice if the vendors provided a
version which validated the imported string.  (For those unfamiliar
with gettext: the function uses a string to look up a locale specific
string.  If it cannot find the locale specific string, it returns the
selector string, which normally corresponds to the text in the "C"
locale.  A checking version could thus verify that the conversion
specifiers in the locale specific string correspond exactly to those in
the selecting string.)
-- 
James Kanze         Tel.: (+33) 88 14 49 00        email: kanze@gabi-soft.fr
GABI Software, Sarl., 8 rue des Francs-Bourgeois, F-67000 Strasbourg, France
Conseils, �tudes et r�alisations en logiciel orient� objet --
                -- A la recherche d'une activit� dans une region francophone

Re: Hungarian notation

[James Kanze US/ESC 60/3/141 #40763]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2877 bytes --]


In article <31a3b1b5.442039268@sqarc> willer@carolian.com (Steve Willer)
writes:

|> kanze@lts.sel.alcatel.de (James Kanze US/ESC 60/3/141 #40763) wrote:

|> >This must be an amazingly brillant compiler...

|> It is. It was written by the FSF people. It's called "gcc". :-) 
|> In particular, gcc checks the arguments of the printf family against the
|> formatter string when the -Wall option is on (actually, I'm sure it's a
|> specific warning, but I always use -Wall).

|> It only warns with these specific functions; if you declare your own
|> function that uses varargs and vsprintf, it won't check it. Yes, it's a
|> hack, but it's a really _nice_ hack.

You should have read the rest of my posting.  Gcc does *NOT* check the
arguments of the formatter string when that string is not a string
literal.  In practice, the string will in fact almost always be the
return value of a function: gettext on X/Open systems, for example.  In
most cases, the string will not yet have been written at the time the
code is compiled.

Since the semantics of gettext are defined by the X/Open standard, gcc
could presumably also recognize this, and treat it as a special hack.
They could also provide a new gettext (or a wrapper function, which in
fact is what I do in C++), which verifies that the conversion
specifications are correct in the string read from disk.

|> >This isn't to say I approve of Hungarian notation, even in C and used
|> >with printf.  Nor to criticize a compiler from generating a warning on
|> >obviously bad code.  Just that this warning won't really be as useful
|> >as one would like in commercial software.

|> You really think so? Perhaps I'm misunderstanding you. A common mistake
|> around here is to write something like:

|> printf("The number is %n\n",mynumber);

|> ...which would only crash when the program hits this line of code, and
|> then only if "mynumber" had a value that made it crash. I can't tell you
|> how many times we've made this mistake and gcc's caught it (actually, I
|> could probably guess: maybe 10 over the last year and a half).

I've never had too much problem with this.  In fact, I cannot remember a
single occurance in 15 years of C/C++ programming.  I *HAVE* been bitten
by two conversion specifiers being swapped during translation.  (I
forgot to insert the X/Open positional specifiers when the word order
changed.)

Given that the actual translation may occur years after the program has
been compiled and released, I really don't consider it a reproach to say
that the compiler doesn't detect the error.
-- 
James Kanze         Tel.: (+33) 88 14 49 00        email: kanze@gabi-soft.fr
GABI Software, Sarl., 8 rue des Francs-Bourgeois, F-67000 Strasbourg, France
Conseils, �tudes et r�alisations en logiciel orient� objet --
                -- A la recherche d'une activit� dans une region francophone

Re: Hungarian notation

[Richard Kenner]

In article <KANZE.96May23144919@slsvi1t.lts.sel.alcatel.de> kanze@lts.sel.alcatel.de (James Kanze US/ESC 60/3/141 #40763) writes:
>You should have read the rest of my posting.  Gcc does *NOT* check the
>arguments of the formatter string when that string is not a string
>literal.  In practice, the string will in fact almost always be the
>return value of a function: gettext on X/Open systems, for example.  In
>most cases, the string will not yet have been written at the time the
>code is compiled.
>
>Since the semantics of gettext are defined by the X/Open standard, gcc
>could presumably also recognize this, and treat it as a special hack.

Indeed somebody else suggested this yesterday.  I'll implement it when
I get a chance.

Re: Hungarian notation

[Jim Kingdon]

> In particular, gcc checks the arguments of the printf family against the
> formatter string when the -Wall option is on (actually, I'm sure it's a
> specific warning, but I always use -Wall).
> 
> It only warns with these specific functions; if you declare your own
> function that uses varargs and vsprintf, it won't check it. Yes, it's a
> hack, but it's a really _nice_ hack.

I probably shouldn't respond to a message which is this widely
cross-posted, but this is incorrect.  If you insert the correct
__attribute__ declarations, gcc -Wall will check a user-defined
function too (I know, this just caught a bug in CVS within the last
week or two).