The Current Code

We think that s a lot more expressive. Here s the whole method. See whether you agree that we have made it more expressive and whether we re justified in taking out the comments we removed:

 public void InsertParagraphTag() { 
 // 
 // On Enter, we change the TextModel lines to insert, after the line 
 // containing the cursor, a blank line, and a line with <P></P>. We set the 
 // new cursor location to be between the P tags: <P></P>. 
 // 
 // handle empty array special case (yucch) 
 if ( newlines.Count == 0 ) { 
 newlines.Add( "<P></P>" ); 
 selectionStart = 3; 
 return; 
 } 
 
 newlines = new ArrayList(); 
 newlines.AddRange(LinesThroughCursor()); 
 newlines.AddRange(NewParagraph()); 
 newlines.AddRange(LinesAfterCursor()); 
 
 // set cursor location 
 selectionStart = NewSelectionStart(LineContainingCursor() + 2); 
 } 

This code still isn t done, as we ll suggest in a moment, but you can see what s happened : we ve taken code that clearly needed some explanation and we ve replaced it with code that surely needs less explanation. You might prefer a bit more than we do, but we ll wager that most readers won t want one line of comment per line of code anymore.