Thinking about code in slides.

codeForSlides.py

# Code for slides:

# 1. Avoid code in your slides, if you have 10 slides and more
# than 2 have code in it, you are making people do a diff review
# while you babble on in front of them...

# 2. Explain the hard concepts with anecdotes, or visuals.

# 3. Code on slides should be taken with MUCH more care to comprehension
# than code in your repository, imagine if you only had 3 seconds
# to understand what was going on.

# 4. This is not about showing how smart you are, it's about conveying the
# and inspiring.

# 5. Consider sharing code as examples online as a reference.

# 6. Know your audience.
# Going to Pycon? Write in python.
# Talking to a group of people about libc, don't use python, use C.
# If you don't know the technical capabilities of your audience, don't put code
# on the screen.

# 7. variable & function names matter much more,
# take a minute and rename everything as if the reader has 2 seconds to
# look at it.
# sometimes concise names are better, but in general be as
# descriptive as possible.
def foo(x):
  return x * x

def square(number):
  return number * number

# 8. Do not care about performance, unless it's the purpose of the talk.
# If it is, show a small change you mad, or describe the way of thinking about
# the problem that resulted in performance gains.
# Who honestly is going to try to run the code you have in the slide?

# 9. The more declarative you are, the easier it is to understand
# confusing and feels buggy.
def getClosest(array, number):
  closest = array[0]
  for i in range(1, len(array)): # (Audience): is there a bug here)
    if abs(i - number) < closest: # (Audience): oh wait is that right?
      closest = i # (Audience): wait go back a slide...
  return closest # (Audience): *phones turn on for the rest of the talk*...

# a bit better
def getClosest(number, array):
  closest = array[0]
  for num in array: # (Audience): Ok, reminder about iterating within a list.
    if abs(num - number) < closest: # (Audience): where is closest?
      closest = num # (Audience): Wait what was num again?
  return closest # (Audience): Ok, I'll just trust that this works...

# declarative
def getClosest(number, array):
  def distance(num):
    return abs(num - number)
  closest = min(array, key=distance)
  return closest

# 10. Do you really need to write all of the code out?
# If you do, consider splitting it up.
# Is the how of that other method REALLY necessary in a slide?

# slide one:
""" Fake Speech:
Finding the closest number in the array resulted in a large business impact.
As simple as running over and passing in the distanceFunction.
"""
def getClosest(number, array):
  closest = min(array, key=distance)
  return closest

# slide two:
""" Fake Speech:
This is how we defined distance, by calculating it this way it aligned with
how it is represented in the real world.
"""
def distanceBetweenTwoNumbers(num, number):
  return abs(num - number)

# NOTE (milroc): the distance function in the second slide isn't the same as the
# first slide. This is because both slides supply different arguments; it'd be
# better to tie them together...but you don't have to.

# 11. don't use obscure parts of a languages grammar:
# your slide should not be a code golf badge of honor
# (any code you write shouldn't to be honest)
# http://codegolf.stackexchange.com/questions/4019/find-minimum-difference-between-numbers-in-array


# NOTE (milroc): Look at how simple these examples are. Explaining this to
# people is not difficult. Explaining the concept you need to talk about is.

May want to show a non-trivial algorithm here; which could be something somebody might actually want to walk through: How does hit-detection work on canvas is (potentially) a good example for vis (I've written various versions of code dozens of times)