We've all groaned over lines of code like this:

  LD  A,#32          ; Load accumulator with 32
  LD  B,#0x1234  ; load B with 1234
  ST  A,           ; Put A into what B points to

BUT!! I opened one of the books I had for learning programming*. What did I see?

  LD  A,#32          ; Load accumulator with 32
  LD  B,#0x1234  ; load B with 1234
  ST  A,           ;  Put A into what B points to

!! I hope that matters have improved since the mid-80s, but it might explain why so many newbies do it (until their hands get slapped).

--Rich

* CIE home study course.

 

Unfortunately, things haven't improved and they probably never will. The quality of code documentation is a primarily a function of the programmer and most programmers simply don't give a hoot and don't know how to write code and comments for the folks down the years who will maintain that code. Then factor in the usual situation of code that has been around a long time and maintained by lots of programmers -- the documentation is rarely maintained properly and with the same effort as the code. One quickly learns that the best strategy is often to ignore the documentation -- it's often just plain wrong. Then toss in the additional problem of code being maintained by people to whom the code's documentation isn't their native language. Oh, and management only cares about meeting schedule and cost goals -- documentation rarely is ever on the radar.

 

The example is a textbook example. The labels are lame, but at least tell the clueless what is going on.

Grab a few thousand lines of undocumented assembler for the other extreme - especially if you need to figure out what it does. Comments may be pretty obvious at times, but that's better than nothing.

 

The example is a textbook example. The labels are lame, but at least tell the clueless what is going on.

Grab a few thousand lines of undocumented assembler for the other extreme - especially if you need to figure out what it does. Comments may be pretty obvious at times, but that's better than nothing.

Or better yet machine code.


I was going to make a similar comment. Obviously, the lame comments here are for educational purposes. Some may think that LDA stands for Larry Does Acid.

 

Well, I can see that the writer of the book was trying to explain to the student what the individual instructions were actually doing, rather than as an example of how to comment the source code.

At a former employer, they were getting low on disk space for the mainframe. What did they do? Stripped all of the comments out of the production job control language files. Yes, they really did that.

I was maintaining some COBOL programs (along with lots of other things) at Hughes Aircraft in the 80's and 90's. One of the programs had a paragraph named "BLAST-OFF." While memorable, it didn't say a whole lot about what the paragraph really did, except that it was an entry point - but that's just slightly more helpful than posting a new thread with a subject of "Help me." 1

I became to be rather detailed in documentation. I'd inherited a mess from a long string of prior programmers, and it took me a couple of years to sort everything out.

 

I want to know what all these American companies are going to do a year or two from now when they go to modify all of that code written by their green card consultant group or the code done offshore. Can you imagine those comments?

A memo was going around the office regarding a protect that is in place to have the controls in place for offshore sourcing of development and application support.

Looks like I will be working at Wallmart in the very near futures

 

I agree with those who have said that the example is OK for a textbook. Especially if the author has just introduced these instructions and adressing modes to the reader. Of course he would have to explain that these are no good comments for real code.

One of my personal favourites is a comment that one of our sub-contractors left behind at the end of a function: "Here xxx got bored and left the project." In another memorable comment one guy admitted that he didn't understand completely what the code was doing, but nevertheless he had to modify it a little bit At least he was honest enough to leave a warning...

I'm rather lazy with comments. But I compensate it somehow because I put much effort into finding good and really descriptive names for variables and functions and whatevever. I have sometimes been criticized by bosses and co-workers that the names I choose are too long. But I think it's better to have a name that takes a bit longer to read, than one where the reader has to spend lots of time to guess what it means. Or to rely on the comment where the name was first introduced - this comment may already be obsolete as someone here has said before.

 

In another memorable comment one guy admitted that he didn't understand completely what the code was doing, but nevertheless he had to modify it a little bit At least he was honest enough to leave a warning...

Funny, that brought to mind a project that I was involved in back in 1980.
A fellow by the name of Jeff, who was pretty bright, but did some dumb things, didn't quite think a section of code was correct, and made some changes to it just prior to a test flight of an experimental radar system. Needless to say, his "corrections" proved a dismal failure. However, he did admit to his mistake and reverted the code.

One of the most humorous things I recall about Jeff was his predilection to playing the game of Hearts on the DEC VAX 11-780 that we were using as a flight test computer. We had a mission set to go, but they nearly scrubbed it because the VAX computer was apparently inexplicably bogged down. It turned out that Jeff was playing the Hearts game, and the minicomputer was spending most of it's time updating Jeff's terminal.

Once Jeff stopped his game of Hearts, the mission went forward successfully.

This was back in the days when having a computer with a clock rate over 2MHz was a big deal. MS Windows didn't exist then (golden days). A hard drive was someplace to go via a wheeled conveyance that was a very long ways away over a bad road.

Enough of my blather.

 

One of the most humorous things I recall about Jeff was his predilection to playing the game of Hearts on the DEC VAX 11-780 that we were using as a flight test computer. We had a mission set to go, but they nearly scrubbed it because the VAX computer was apparently inexplicably bogged down. It turned out that Jeff was playing the Hearts game, and the minicomputer was spending most of it's time updating Jeff's terminal.

Once Jeff stopped his game of Hearts, the mission went forward successfully.

This was back in the days when having a computer with a clock rate over 2MHz was a big deal. MS Windows didn't exist then (golden days). A hard drive was someplace to go via a wheeled conveyance that was a very long ways away over a bad road.

Same thing happened to me except I was the culprit. We had several PDP 11/34s at work. I was a lowly tech but I knew a bit about them. I started running Adventure. All of a sudden I hear all of this screaming and running around going on and I hear "I think it's coming from back here"! A bunch of software nerds come running into my office and say "it's you! shut it down"! Apparently I was hogging all of the resources.

And a bit off topic but I used to work at Texas Instruments. We had one particular computer that had speech synthesis. It would announce any system errors.

One error was "Shut er down Clancey. She's a pumpin sludge". For those that don't know Texas Instruments got their start in the oil industry.

 

Speaking of "Adventure" (I think the executable was advent.exe...) do you remember dungeon.exe? They shipped DEC VAX computers with it in the late 70's-early 80's. Later, dungeon came out on the commercial market as Zork. I've been known to burn up some CPU time playing dungeon in the past.

Another one was Empire, where you were at war with the computer. You started off with one city, the default production was Armies, but you could build Tanks, Fighters, Bombers, Aircraft Carriers, Destroyers, Troop Transports, etc - only Tanks and Armies could capture other cities. Transports could carry three Tanks or six Armies. Once you had quite a few armies built up and on "automatic pilot", you could slow the system to a crawl...

 

Speaking of "Adventure" (I think the executable was advent.exe...) do you remember dungeon.exe? They shipped DEC VAX computers with it in the late 70's-early 80's. Later, dungeon came out on the commercial market as Zork. I've been known to burn up some CPU time playing dungeon in the past.

Another one was Empire, where you were at war with the computer. You started off with one city, the default production was Armies, but you could build Tanks, Fighters, Bombers, Aircraft Carriers, Destroyers, Troop Transports, etc - only Tanks and Armies could capture other cities. Transports could carry three Tanks or six Armies. Once you had quite a few armies built up and on "automatic pilot", you could slow the system to a crawl...

Those old text games were the best. No graphics designer can program a better scene than the one in your own mind.