3.6 Clarity

A program should read like a technical paper, organized into sections and paragraphs. Procedures form a natural section boundary. You should organize your code into paragraphs, beginning a paragraph with a topic sentence comment and separating it from other paragraphs with a blank line. For example:

// poor programming practice
temp = box_x1; 
box_x1 = box_x2; 
box_x2 = temp; 
temp = box_y1; 
box_y1 = box_y2; 
box_y2 = temp; 

A better version would be:

/* 
 * Swap the two corners  
 */ 

/* Swap X coordinate */ 
temp = box_x1; 
box_x1 = box_x2; 
box_x2 = temp; 

/* Swap Y coordinate */ 
temp = box_y1; 
box_y1 = box_y2; 
box_y2 = temp;