readability

readable.py

"Programs must be written for people to read, and only incidentally for machines to execute."
source: http://web.mit.edu/alexmv/6.037/sicp.pdf

# this part was really elegantly done, it's readable, easy to understand, commented, concise.  
# it was magical but wasn't too out there, just needs a unit test and all is good.  

# Get subboxes
sub_areas = self.responsearea_set.all()
sub_areas_draw = map(lambda a: a.drawables(), sub_areas)
# Flatten
sub_areas_draw_flat = [d for sub_list in sub_areas_draw for d in sub_list]

# while list comprehension is great, it still needs to be used effectively.  
# the logic is complicated, hard to follow, hard for others to to extend and maintain.  

def _generate_name_entry(self):
  """ Create a list of tuples for name entry """
  name_box_w, name_box_h = NAME_BOX_SIZE
  name_label_x, name_label_y = NAME_LABEL_TOP_LEFT
  nb_half = NUM_NAME_BOXES / 2.0
  tl_x, tl_y = NAME_ENTRY_TOP_LEFT
  
  # Add the dashed boxes
  name_entry = [(
    'box', (x % nb_half * name_box_w) + tl_x,
    (x>=nb_half) * (name_box_h) + tl_y, name_box_w, name_box_h,
    { 'fill_color':WHITE, 'stroke_color':BLACK, 'dash':[1,2] }
    ) for x in xrange(NUM_NAME_BOXES)
  ]

  name_entry.extend([
    ('text', name_label_x, name_label_y, None, None,
        { 'text': 'First', 'font_size':10}),
    ('text', name_label_x, name_label_y + name_box_h,
        None, None, {'text': 'Last', 'font_size':10})
  ])

  return name_entry

# same result using list comprehension.  but no line of code is trying to do too much.  
# generating tuples and labels can be clearly separated so each piece is easy to read and modify  

def _generate_name_entry(self):
  """ Create a list of drawables for name input """
  w, h = NAME_BOX_SIZE
  x, y = NAME_BOX_TOP_LEFT
  label_x, label_y = NAME_LABEL_TOP_LEFT
  
  labels = [
      ('text', label_x, label_y, None, None, { 'text': 'First', 'font_size':10}),
      ('text', label_x, label_y + h, None, None, { 'text': 'Last', 'font_size':10})
  ]
  
  box_style = { 'fill_color': WHITE, 'stroke_color': BLACK, 'dash': [1,2] }
  first_name_boxes = [('box', x + box_i * w, y, w, h, box_style) for box_i in xrange(NUM_NAME_BOXES)]
  last_name_boxes = [('box', x + box_i * w, y + h, w, h, box_style) for box_i in xrange(NUM_NAME_BOXES)]
  
  return labels + first_name_boxes + last_name_boxes