Another good example of proper usage of comments within code is to look at some of the system stored procedures.  In the MS world, try looking at sp_get_composite_job_info located in msdb.  I was just in there today trying to gather some meta data of the jobs on the server.  I have learned considerably from reviewing these procs, and the comments are extremely helpful.

- Paul

Tom,

I'm not sure I agree with the concept that the amount of typing should control how code is written.  After twenty years of programming, I've realized that you generally pay dearly when doing maintenance for shortcuts taken in development.  As one of my professors once asked, 'if you don't have time to do it right, how can you have time to do it over?'.

Mattie

Mattie,

My comment was in regard to the :

ReadyStatus = ( ReadyStatus = False )

If it took 10 lines of code to do the equivalent, and the above is correct, you shouldn't be adding an extra 9 lines of code because it may not be apparent to a junior programmer.  This would handicap you greatly if you cannot use advanced features of the language.  As a twenty year vet, I mostly see the opposite, where a junior coder did 10 lines of code where there is already a built in function that did the same thing in 1 line.

Mattie,

We are of the same mind.  I have seen white space reducers for PERL and C++.  This all comes from the days when we were storing source code on flippies (You remember: Floppies that you notched so that you could use bothe sides).

Then there were COBOL programmers paid by the line.  This yielded the one word per line junk.

VB.Net makes my code pretty.  The auto indent helps me spot logic errors before I even try to single step.  Go to the line above a function definition and type three tick marks (''').  Instant XML documentation.  Just fill in the blanks.  I can look at the object browser and not have to open the code to find the right function.  (Hey. Subs are functions that return Void)

Comment vs Not Comment.  I vote comment.  Your comments should be meaningful.  Function UpdateOrderHistory(ByVal OrderNumber AS Integer) as Boolean.

' This function updates the order history.

My boss said, "Well, no sh**!  I thought it might make coffee or something."

Oh, it may not be that funny.

_sql = "UPDATE Inventory SET QOH = QOH + " & CSTR(ReciptQuantity)

Found this in production code.  Customer wondered why his inventory was "over stated".

1801  --Bundled Services, not including VOIP your documentation is out of date, and the code hasn't even been touched

Mattie,

That might be true except for one thing (I believe this was one of your previous good points, as well)... the code is in a proc called ApplyAdjToPOTS.  On the outside chance that someone doesn't know what "POTS" is (an industry standard acronym), we put it in the header of the code... "POTS: Plain Old Telephone System".  We have totally separate systems to drive Wireless, VOIP, and a couple of other goodies.

I will also now shamelssly plug my SQL PROGRAMMING STYLE book that deals with these issues

Shameless or not, I'm going to have to get a copy of that one... thanks for the tip, Joe...

The point is, Mark, instead of having to read through the code to find what you want, you only have to lightly scim through the comments to find out what a section of code does and WHY it was written.  If you are totally unfamiliar with the code (someone else wrote it) and you've been assigned to do a light mod to the code, it can save you a bit of time.

You can read code... without looking back at JT's code, WHAT does this do?  You have 3 seconds, my friend because your boss is standing over your shoulder, knows you can read code because you've been bragging all day that "if you cant do that then you shouldnt be any where near the code", and expects you to find and fix a problem while he or she is waiting... yes, yes... anyone worth their salt can read this and figure out HOW it's doing something but you have to study it for more than 3 seconds to figure out WHY it's doing it...

    SELECT NVL(c.data_type_cd, 'STRING'),
           c.value_txt,
           c.value_dt,
           c.value_nbr
      INTO v_data_type_cd,
           v_value_txt,
           v_value_dt,
           v_value_nbr
      FROM example.idt_constant c
     WHERE c.constant_nm = p_constant_nm
       AND c.site_cd = p_site_cd;

Now, go back and look at JT's code and you'll find the comment that saves so much time...

    /* found constant, determine data type */

The point is, Yes, if you can't read code, I agree, you probably shouldn't be anywhere near the code.  If you can't eventually figure out "why" (what the purpose of) some undocumented code was written, I agree... you shouldn't be near it.  But, simple little sprinklings of good comments even on "obvious" code is a real time saver when troubleshooting.   For non-obvious, complicated, or "tricky" code, you will need more substantial comments.

Then, there are QA people... they are NOT necessarily people who have a deep understanding of how to read code but they do need to be able to quickly map out what a proc is supposed to do so they can setup a test case to figure out if the code actually did what it's supposed to especially if it writes to a table.  Simple but well written comments can and do save QA people huge amounts of time.