BS: Is this comprehensible?

Subject: Is this comprehensible?
From: Jon Freeman
Date: 06 Dec 00 - 10:32 PM

I am seething at the moment for being marked down on a programming assignement in my course at HE level for not putting comments in a programming assignment. The tutors remarks were "{comments please} tell other users what you are doing and thinking". Apart from the fact that I don't believe that users ever read source code (programmers do), I commented that I did not believe that a program of such a trivial nature warranted comments and he half agreed saying "Yes but you have to remember this is an artificial environment and I want comments so that is how it is" and the fact that he had not mentioned that in the assessment criteria (although he had again probably wrongly used the term user) is apparently irrelevant.

Anyway, that is mainly by the by. What I realy want to know is whether non-programmers can understand this code (bear in mind what would be commented on would be program logic and uses of variables rather than the meaning of a words like integer - something that holds a whole number value, and real - something that holds a decimal value or the structure of pascal, in other words the bits I would expect to be hard for someone who has never read Pascal or any other programming language - or a user):

  program Wages;    

var
     Employee: integer;
     Hours:    integer;
     Pay:      real;
    

begin
     for Employee := 1 to 5 do
         begin
         Write('Enter hours worked: ');
         Read(Hours);
         if Hours > 20 then
            Pay := Hours * 4.00
         else
            Pay := Hours * 3.75;
         WriteLn('Pay due = ', Pay:5:2);
         end;
  end.  

Oh well I guess that if nothing else, I should be glad that a course I have been on at HE level since August has at least got me this far in programming.

Jon

Subject: RE: BS: Is this comprehensible?
From: Sorcha
Date: 06 Dec 00 - 10:38 PM

Jon, to your instructor from me: No, as a "user" comments on this sort of thing are neither helpful nor useable to me. HTML yes, Java script, maybe someday,(at least I know what it looks like and what it does) but this I don't need as a User.

Pity you can't tell him to kiss off. Good Luck with your courses. Wish you all the best, From Wyoming, US.

Subject: RE: BS: Is this comprehensible?
From: bflat
Date: 06 Dec 00 - 10:50 PM

Jon, Just perhaps the user is not the end person but rather the System Analyst. As a former analyst, I often read the code during the testing phase. I found it to be helpful and documentation is essential as the iterations accumulate. It can be very worthwhile. Still the onus is on the instructor to clarify his/her requirements.

Always remember to ask lots of questions of "users." Most of the time you will find they aren't expressing their needs clearly. Best of luck.

bflat

Subject: RE: BS: Is this comprehensible?
From: Jon Freeman
Date: 06 Dec 00 - 10:54 PM

fair comment bflat but for a single iteration in 5-6 lines of code?

Jon

Subject: RE: BS: Is this comprehensible?
From: Jeri
Date: 06 Dec 00 - 10:58 PM

I don't know programming, and I could figure out what the above is supposed to caluclate\do.

  begin
    for Employee := 1 to 5 do
        begin
        Write('Enter instructor name: ');
        Read('Name);
        if Name = Mr Dumbass Teacher then
           Write('YOU TURKEY!!!')
        else
           Write('Oh, never mind')
                      end;
   end. 

Subject: RE: BS: Is this comprehensible?
From: Jeri
Date: 06 Dec 00 - 11:03 PM

Jon, given that others in the class don't have your experience, maybe he's just trying to get them into the habit of documenting things?

Subject: RE: BS: Is this comprehensible?
From: IvanB
Date: 06 Dec 00 - 11:10 PM

I have to assume Jeri's right, Jon. Most of my computer courses required documentation of asinine things that, to me, we self-evident. But when I started writing major programs, I made sure for those who'd have to work with my code later (analysts and/or programmers) that every section was commented with what the code in that section was designed to do. I hope he's misused the term 'users.' I doubt the normal user has the knowledge or interest for the comments to be of any use.

Subject: RE: BS: Is this comprehensible?
From: Jon Freeman
Date: 06 Dec 00 - 11:15 PM

I suspect that is part of it Jeri but if that is the case, why mark me down because I have experience and a distinction in programming at a lower level that in fact taught more than this module has rather than taking that into account? This was taught by the same college. Im not sure whether to feel insulted by having to put those lines together or whether to feel that the college does not rate its own teaching.

bflat has mentioned one very good reason for comments and I agree that programs can get to a point where comments are necessary, either to explain logic or simply to explain what loop within a loop (the official term for a loop is Iteration one of 3 basic and essential program constructs) is doing what. Even if I am just hacking for my own benifit I have to mark starts and stops of these to keep track of what begins and ends where so I do appreciate their value.

Jon

Subject: RE: BS: Is this comprehensible?
From: Sorcha
Date: 06 Dec 00 - 11:28 PM

Maybe he just wanted comments on the course as a whole, or the exam itsself. Maybe he is just a wanker. If your can't flay them with your facts, baffle them with your bullshit. That is the ONLY way to get through any school Jon. Sorry, it is a fact of Academic Life. There is no other reason I recieved full marks (except for maths) during my "educating seasons".

You need to learn to "play into the game"...it is not easy, but it is an aquired skill. Think like a parrot....Repeat After Me......

Self-Important teachers/professors are abundant in Colleges, and they want to remain Self Important regardless of whether they know anything or not. Actually, they MUST remain self important in order to retain their postion, so they must be appeased. So appease.......just to get the piece of paper, then you can go your own way.

Bite your tongue for a while even if it is difficult.

Subject: RE: BS: Is this comprehensible?
From: GUEST,Sarah
Date: 06 Dec 00 - 11:39 PM

I don't know, Jon; it's all Assembler to me. But I was, for my sins, married to a programmer, and he used to say, "Document, document, document." His theory was that, whether or not the User could understand, what about the programmer who gets stuck with his program, having to update and alter it after he himself had moved to greener pastures?

It also has something to do with CYA at a lot of places, if his job history was anything to use as reference.

Sarah

Subject: RE: BS: Is this comprehensible?
From: Jeri
Date: 06 Dec 00 - 11:41 PM

Jon, he's just playing by his rules - the same one's that apply to students who haven't taken the course before. The whole problem is, you HAVE taken the course before and you have to go through it again, and it's simple to you.

Sorcha, I think by "comments," Jon means a bit of text next to each line of code that says something like:
Write('Enter hours worked: '); this tells the user to enter the hours worked. Of course, they probably have those REM thingies - like I said, I don't know much about it.

Subject: RE: BS: Is this comprehensible?
From: Jon Freeman
Date: 06 Dec 00 - 11:58 PM

Yep Sarah, but where do you draw the line. I can not imagine any programmer failing to understand that code without comments and still fail to see the need to document 6 lines of code.

I guess I could have written:

  begin
     for Employee := 1 to 5 do {step through each employee}
         begin
         Write('Enter hours worked: ');{prompt for hours worked}
         Read(Hours){accept user input for hours worked};
         if Hours > 20 then{compare hours worked to 20 and take appropriate action}
            Pay := Hours * 4.00{calculate pay if more than 20 hours are worked}
         else
            Pay := Hours * 3.75;{calculate pay if 20 or fewer hours are worked}
         WriteLn('Pay due = ', Pay:5:2){output pay due};
         end;{repeat process for next employee until 5 are covered}
  end.  

What I am trying to ask here is whether THIS program waranted comments rather than whether comments can be useful within programming. I still fail to see that any programmer, even one unfamiliar with pascal but familiar with C or Java would need comments as an aid to understanding the program (and I believe over use is a pain in the ass) and that whether, as appears to have been indicated that users would be interested in such things.

As regards pain in the ass documentation, this assignment was documented with flow chart, trace diagram and data table.

Jon

Subject: RE: BS: Is this comprehensible?
From: CarolC
Date: 07 Dec 00 - 02:12 AM

Subject: RE: BS: Is this comprehensible?
From: CarolC
Date: 07 Dec 00 - 02:18 AM

Oops.

I was just going to say that in my (several) years of being a college student, I have frequently noticed a disconnect between what the teacher required, and what would be applicable in the real world.

Last spring semester, I took a sociology course, the textbook for which was written when "The Actor" (Reagan) was still President of the U.S., and the Soviet Union was still intact. The world is a whole different place now.

Carol

Subject: RE: BS: Is this comprehensible?
From: MudGuard
Date: 07 Dec 00 - 03:46 AM

Jon,
as you might remember I am a professional software programmer.
I think the above example should need no comments.
I myself use comments mainly to write at a function declaration what the function is supposed to do and what the parameters mean, what is returned and what happens if errors occur.
Elsewhere in the code I only write comments if I do something in an unusual way (because it might be more efficient...)
But in a teaching environment, I also insist on more comments than really necessary. I offen recommend to write the algorithm first as comments only like in

//for each of the five employees
//    ask for hours worked
//    check if more than 20 hours
//       yes: multiply by 4
//       no: multiply by 3.75
//    output calculated pay

and then (after once again thinking about it) replace each line of comment by the actual code (or write the actual code before the comment).

MudGuard (still remembering Great Orme!)

Subject: RE: BS: Is this comprehensible?
From: GUEST,Fibula Mattock
Date: 07 Dec 00 - 05:22 AM

Comments are so helpful when you're picking up and developing someone else's work, and I had to spend most of last summer deciphering uncommented code so I'm all in favour of them. I agree that the above example is small enough to be understood, but the good programming practice seems to be to always include at least one line at the start to explain what your program does, and then a line or two for each function (stating explanation, arguments, etc.). I suppose it all boils down to this hypothetical "good programming practice". We got marks taken off in university for not using correct indention. Then I got a programming job and saw that most of the code was just hacked fixes and indention barely entered into it. Still... in an ideal world...

Subject: RE: BS: Is this comprehensible?
From: Llanfair
Date: 07 Dec 00 - 05:39 AM

I think I'm one of those "users" to whom any form of programming language is incomprehensible, wether it is explained or not, but college tutors, in my experience, tend to be pedantic, because to be flexible is too much like hard work.
Cheers, Bron.

Subject: RE: BS: Is this comprehensible?
From: GUEST,Roger the skiffler
Date: 07 Dec 00 - 05:51 AM

Jon, I've worked in higher education for over 30 years, and I agree many course & exam requirements make little sense to those of us who inhabit the real world!
That said, you just have to bite your tongue and play the game their way to get the outcome you clearly deserve. Once you've got the bit of paper,you can revert to common sense!
Best wishes: "nil carborumdum illigitimi".
RtS

Subject: RE: BS: Is this comprehensible?
From: Banjer
Date: 07 Dec 00 - 06:03 AM

As a user who has little idea what actually makes a program do what it does I care not for comments. All I want, after paying the sometimes high price for the program is that it works, does what I want it to do, and doesn't lock up my pewter.

Subject: RE: BS: Is this comprehensible?
From: Grab
Date: 07 Dec 00 - 08:34 AM

A description of the formatting of the I/O might be useful (eg. saying what the "5:2" does for formatting - I guess you're assuming the pay doesn't have to any more accurate than cents, and that they're not paid more than $99999.99 a month). You're also assuming that there are only 5 employees - making this a constant so it can be changed easily might be an idea. And a comment saying the pay structure might be useful - these would be replaced by constants too in a real program.

But you're right, it is a pretty trivial bit of code.

Grab.

Subject: RE: BS: Is this comprehensible?
From: GUEST,Russ
Date: 07 Dec 00 - 09:48 AM

Pardon me while I look for my geezer-sage hat.

I've been teacher, student, and programmer. As a teacher, I don't always do exactly what my students think they want in exactly the way they think they want me to do things, and I am happy to listen to their suggestions and gripes. However, I must usually reply by asking them to trust me and humor me. They must trust that I am not being dictatorial for the pure love of abusing power and be willing to go along with he gag for a while. If they cannot give me that trust, they really need to go to another teacher who can inspire it. I've learned myself over and over that you sometimes cannot see the point of the teacher's wishes until you have had certain experiences yourself. Before I actually began teaching I was a good (but definitely not a passive) student with definite opinions who occasionally fought teachers in various subtle and nonsubtle ways. After I had actually taught for a while, my approach to studenting changed. I became increasingly willing to accede to my teacher's wishes whether or not I can see the point. It is an approach that has reaped me significant benefits over the years.

So, whether or not a particular bit of code needs commenting or not is not the real issue. You teacher thinks that commenting is a GOOD THING and wants you to get into the habit of doing it. I happen to agree in this case.

HOWEVER, all this being said, in my opinion the most important statement you make in your initial post is that "he had not mentioned that [commenting requirement] in the assessment criteria". If I am going to claim that a teacher has a right to expect you to do things his way for the duration of the student-teacher relationship, the teacher has a an equal DUTY to inform you, in detail, of his expectations. No informing you of the details has his expectations was not just a minor OOPS, it was a major faux pas. How can you hope to fulfill expectations you don't know about?

Subject: RE: BS: Is this comprehensible?
From: Bert
Date: 07 Dec 00 - 11:41 AM

You are 100% correct Jon. When I was teaching programming I used to teach my students 'Do NOT use COMMENTS'. And they knew that BEFORE any test and they were taught why.

Your variable names and procedure names should be chosen carefully enough that your code is self explanatory.

That's exactly what you did. The real reason for NEVER using comments is that comments NEVER get updated.

Look at ANY old piece of code that has comments in it and you will find comments which are out of date and are therefore wrong and misleading.

The only exception to this is when you are using a language which does not contain modern programming language structures (like HTML and other pseudolanguage stuff) and then it may be necessary to occasionally add an explanation.

But in Pascal, Cobol, Fortran, Ada, and heaven forbid even C or Perl. Comments are not a substitute for good programming.

Bert.

Subject: RE: BS: Is this comprehensible?
From: GUEST,Fibula Mattock
Date: 07 Dec 00 - 11:48 AM

Bert! Please don't make my life harder!! I totally agree that meaningful variable names etc. should be assigned (e.g. using Hungarian notation) but surely comments are useful? And if the code is updated a program log should be used to keep track of changes. Comments have got to be a necessary part of good programming. Not every line - just enough to organise the code. Perhaps 10% comments? I am so glad my days of staying in work til midnight to decipher someone elses buggy code are OVER! Long live the return to student life!! But I hope anyone in my last place of work understands the code I left behind.

Subject: RE: BS: Is this comprehensible?
From: Bert
Date: 07 Dec 00 - 12:04 PM

Nope, a program log SHOULD be used but in practice it very rarely is. If your code is written well enough that it is self explanatory the comments are unnecessary.

Bert.

Subject: RE: BS: Is this comprehensible?
From: GeorgeH
Date: 07 Dec 00 - 12:34 PM

bert, your teaching is a fine example of why so much programming is bad . .

A good rule is that EVERY branch and EVERY loop should be documented. And IMO Jon's teachers were right to mark him down (mildly . .)

If comments are not updated that's poor code maintenance.

One person's "obvious" bit of code is someone else's nightmare . .

Why do you think Microsoft produce unmaintainable bloatware?? (OK, I'm guessing at that "why").

If your're on a programming course the object is to produce exemplary code, not just comprehensible code.

G.

Subject: RE: BS: Is this comprehensible?
From: IvanB
Date: 07 Dec 00 - 12:50 PM

Russ made a point above that I was going to include in my initial post and forgot - that the instructor is irresponsible for marking Jon down on something which wasn't included in his instructions. That, in itself, deserves a failure in 'commenting.' Of course, the instructor isn't striving for a grade.

Subject: RE: BS: Is this comprehensible?
From: Jim Dixon
Date: 07 Dec 00 - 04:25 PM

I got out of the programming business a long time ago. I was a programmer for about 12 years in the 1970's and 80's. (I wrote in COBOL. I'm not very familiar with Pascal, but it's easy to guess what your program is doing.) My technological knowledge may be mostly obsolete, but I'll tell you what I think anyway.

In real life, it's not likely anyone would ever write such a short program as a stand-alone item. It could only be an exercise, an experiment, or a small part of a much larger program. As a professional programmer, you would write hundreds of modules of this size in a year's time. Think of yourself a year from now looking back on this page and trying to remember why you wrote it, and trying to remember what distinguishes this particular module from the hundreds of others you have written. Or think of yourself looking for a particular program that you had written a year earlier, flipping though a stack of similar programs, having your eyes land on this one, and wondering for a second or two whether this is the one you were looking for.

(If you haven't done this with programs, maybe you have done it with songs or tunes.)

What would help you most? A title! I know your program already has a title -- "wages" -- and this might be sufficient for the computer. If you type RUN WAGES, it will probably run the right program. But in real life, it's not likely that a sizeable company would have only one program of this size that deals with wages. You need something more descriptive.

I'd say a program (subroutine, whatever you want to call it) of this size deserves about one or two lines of explanation.

Let's go back to the music analogy. Suppose you've got a stack of tunes that you've written down and performed at various times. You're looking for one that you've used before, so you can use it again. What would you like to have written at the top of the page, to help you find the one you want? You'd want a title for sure. But you may have several versions, for example:

Turkey in the Straw
Turkey in the Straw in G
Turkey in the Straw in D
Turkey in the Straw with guitar chords
Turkey in the Straw arranged for guitar and fiddle
Turkey in the Straw with tablature for mandolin
Turkey in the Straw parody for George's birthday

Sure, any programmer can read the code and figure out what it does, just like any musician can read the notes and figure out what a tune sounds like. But when you're flipping through pages looking for something, and you're in a hurry, you want something that will save you time. That's what good comments do.

Subject: RE: BS: Is this comprehensible?
From: Jon Freeman
Date: 07 Dec 00 - 08:12 PM

Thanks everyone for you feedback. I still feel very hardly done by but that it life I guess.

The scenario was that I have programed before both as a student where I received distinctions in every programming assignment I have ever done both in a programming module at National Level and in a module called Implementation of IT systems at HNC level and at one time, a keen hobbyist programmer who has written programs of several thousand lines, one of which was used to keep the physiotherapy treatment appointments for Llandundo Hospital for about 10 years while my mother worked there.

This programming unit was something of a joke (not the teachers fault, he had 1 hour a week to try to teach programming) and it took 7 weeks for people to reach the ability to write this code using a repeat until loop (it turns out than no-one else within the group other than me was even aware of a for loop or a while loop). After getting bored for 3 weeks, I agreed with the teacher not to attend but cleared the requirements with him.

The assignment was a 1 hour time constrained one asking for a trace table, a data table, a flow diagram and "a pascal program which usesall the programming constructs".

The assessment criteria says:

Pass: "The solution should be completed in the time allowed. The trace table, data table should reflect the problem at hand. Minor inaccuracies may exist within the flow diagram. The program itself should reflect the design and show a level of programming competence.

Merit: As for pass. The trace table, data table and flow diagram should accurately reflect the problem. The programmed solution must show a reasonable level of programming competence.

Distinction: As for merit. The programmed solution should show a higher degree of programming competence. The solution must work and its design and build must have taken other potential users into account.

A completed in about 20 minutes (even though I've not been taught flow charts and trace diagrams - it was JSP before) and handed it in. The tutor, say "let me check", read through and say's "that's fine".

I come back the next week to find that what I still consider meets distinction criteria makes a merit, a tutor that says "that's life and won't discuss" and that he had given everone present the week before a pretty near duplicate model of what was expected.

Instead of me reflecting the fact that I am currently far more competent than any other member of the group, I get downgraded for a lack of a comment. I still think this is unfair.

Jon

Subject: RE: BS: Is this comprehensible?
From: Jon Freeman
Date: 08 Dec 00 - 12:02 AM

OK, I get the message, I can't handle academic life and never could. The case of what I consider to be injustice is not worth discussing, the fact that I am a JoeClone here and correct HTML errors is totaly irrelevant to the great FrontPage that they use and I have to prove I can go <href=.... via that moronic package to prove I can make a link, the fact that I have helped getting Hearme and PalTalk established here is irrelevant to any communication skills they want to know about..: I just need to learn to play by the rules....

Please someone tell me what the point in bothering is.

Jon

Subject: RE: BS: Is this comprehensible?
From: GUEST,Fibula Mattock
Date: 08 Dec 00 - 09:12 AM

For a more lighthearted approach:
How to write unmaintainable code

Subject: RE: BS: Is this comprehensible?
From: Jon Freeman
Date: 08 Dec 00 - 09:48 AM

I love it (or what I can understand of it).

Changing the subject, can any of you programers out there tell me how to pass a C++ member function as a parameter?

I can use something along the lines of

void ForEach(void (*Function)());

to call a non-member function such as

void (DoThis);

but I can't get it to work with a member function.

This is just for something I am playing around with for my ammusement. C++ and object orientated programming are not covered on my course.

Jon

Subject: RE: BS: Is this comprehensible?
From: MudGuard
Date: 10 Dec 00 - 04:42 AM

Hi Jon, it will only work with a static member function. Each non-static member function has one hidden parameter (the this-pointer) which makes it impossible to use the member function as a parameter
They are always called in the form variable.function(parameters)
Non-static member functions are associated to an instance of the class (the one for which they are called).

Static member functions do not have access to "this", they can only access static member variables. But they can be used as parameters.
They are called from within the class by function(parameters) and from without by classname::function(parameters).
Static member functions are not associated with an instance of the class.

HTH
MudGuard

Subject: RE: BS: Is this comprehensible?
From: Jon Freeman
Date: 10 Dec 00 - 10:53 AM

Thanks Mudguard,

I will have a play next week. This one started with Tim,one of my brothers, asking me for some guidance for a C++ assignment he has to do (lucky sod, he has less on paper than me programming wise but he managed to get on a course in Liverpool which awards a post-graduate certificate- much as I hate study, I would have enjoyed that course) and I thought it would be nice to try to implement some form of ForEach function to iterate through the linked lists he is using and call a function to perform a specif task rather than repeating the same code to work through the lists for several functions.

I may be completely on the wrong lines anyway but at least it is a challenge for me to see if I can come up with that sort of solution.

Jon

Subject: RE: BS: Is this comprehensible?
From: MudGuard
Date: 10 Dec 00 - 04:24 PM

You could also use an int parameter (called e.g. WhichFunction) which takes (e.g.) value 1 for function 1, 2 for function 2 and so on, and within your ForEach function you have a

  switch (WhichFunction)
  {
  case 1: function1(...);
      break;
  case 2: function2(...);
      break;
  //and so on
  }
  

MudGuard

Subject: RE: BS: Is this comprehensible?
From: Jon Freeman
Date: 11 Dec 00 - 05:10 AM

Thanks again Mugdguard but not for what I was trying to do. Assuming I am thinking straight, that would require a modified ForEach for derived classes but what I was trying to achieve was ForEach in the base class that would allow me to define new functions that could be called from derived functions.

Like I said before though, I am just playing with ideas for my ammusement (hoping I might learn something in the process). I rarely attempt programming these days but when I do, I tend to use C++ Builder or Delphi (I hate VB) where much of the work is done for me.

Jon