[jpatte]

I think the author missed the opportunity to show how choosing better identifiers for his example would have eliminated the need for comments immediately. Also notice how his comments were actually bad from the beginning: it said the method returns something even though it doesn't.

Example:

  def printPlayerLineup(playerPositionByNames)
    batOrder = 1
    playerPositionByNames.each do |name, position|
      puts "#[name} bats #{batOrder} and plays #{position}"
  	batOrder += 1
    end
  end

There are also a few tips to give about how to pick good names. For example if you expect an array of player names the argument should be called `playerNames`, not `players`. Another example is function names should always start with a verb.

Also, if you end up writing comments just to specify types, consider using a statically typed language instead.

[NateDad]

What am I allowed to pass into this function? a hash? a list? To me, player position by names sounds like a hash of name:position. Your code assumes the input is in bat order, but doesn't say that anywhere (and how does that work with a hash?). This is why you need comments.