Zealous overuse of comments

[iago]

I dunno, why I'm posting this here and not on programming, but eh?

This is my prof's sample solution to our assignment (well, part of it):

Code Select Expand

// CLASS: EventList
//
// REMARKS: Extends our basic linked list class to be a list
// of events.  This requires only the implementation of a comparison
// operation suitable for this data type.  We also rename the return-
// first-item operation to something more mnemonic.

// Again, if you didn't make OrderedList abstract, it just means
// more duplication of code - this should show you a great example
// of why we use abstract classes!
//
// INPUT: None
//
// OUTPUT: Printing the list is possible (implemented by superclass).
//
// Externals: Requires Event.
//
//-----------------------------------------

public class EventList extends OrderedList {

      //constructor - just make an empty list
      public EventList() {first = null;}

    //------------------------------------------------------
    // smaller
    //
    // PURPOSE:  is event 1 smaller than event 2?
    //
    // PARAMETERS: None.
    //
    // EXTERNAL REFERENCES:  Requires Event.
    //------------------------------------------------------

      public boolean smaller(Object anObject, Object newData) {
            //is the Object supplied smaller than the new data?
            //The generic list stores objects, which means we have
            //some straight-forward (if tedious) casting to do to be
            //able to do the comparison.
            boolean result;
            //event 1 is smaller than event 2 if it is for an earlier time
            if ( ((Event) anObject).getTime() < ((Event) newData).getTime() )
                        result=true;
            //it's also smaller if they are at the same time and event 1 is for
            //an earlier flight number than event two.
            else if ( ((Event) anObject).getTime() == ((Event) newData).getTime()) {
                  if ( ((Event) anObject).getPlane().getFlightNum() < ((Event) newData).getPlane().getFlightNum())
                        result= true;
            //otherwise event 2 is smaller than event 1.
                  else
                        result= false;
                        } //inner if
            else
                  result= false;
            return result;
            }

    //------------------------------------------------------
    // insertByTime
    //
    // PURPOSE:  just renaming the basic insert-in-order to make more
    // sense for use with events.
    //
    // PARAMETERS: an Event to insert.
    //
    // EXTERNAL REFERENCES:  Requires Event.
    //------------------------------------------------------
      public void insertByTime(Event anEvent) {
            insertInOrder(anEvent); }

    //------------------------------------------------------
    // getNextEvent
    //
    // PURPOSE:  just renaming the basic return-first to make more
    // sense for use with events.
    //
    // PARAMETERS: None.
    //
    // EXTERNAL REFERENCES:  Requires Event.
    //------------------------------------------------------
    public Event getNextEvent () {
    //remove and return the next event, stored at the top of the list
          return (Event) removeFirst();
      }
}
Now, I know that comments are important, but count the lines!  it's like 90% comments! :-(

[Eibro]

I thought comments were supposed to increase the readability of code
Most of that code is self-documenting, the comments just make it harder to read...

[Yoni]

eh
There's code somewhere in there?

[iago]

There's 19 lines of code, not counting " } " but counting function headers and variable definitions.

There's also 57 lines of comments.

Yoni, do the math
Oh fine, I'll do it.. 57 + 19 = 66 lines of code, (19 / 66) * 100% = 28.7878787878787878787878787878788% code.  Rounded, of course.