Checkpoint 6.1.1. Exercise: Navigating poorly documented code.
Consider the following function for two minutes to see how far you can get just by looking at the code snippet alone.
def findAllPrevious(self, name=None, attrs={}, text=None, limit=None,
**kwargs):
return self._findAll(name, attrs, text, limit, self.previousGenerator,
**kwargs)
Was two minutes sufficient to understand it? Even if you had written this code yourself six months ago, how likely would you be to remember what it does now? Briefly explain.
Now consider the prototype with a docstring.
def findAllPrevious(self, name=None, attrs={}, text=None, limit=None,
**kwargs):
"""Returns all items that match the given criteria and appear
before this Tag in the document."""
return self._findAll(name, attrs, text, limit, self.previousGenerator,
**kwargs)
Now go to the following link: Documentation Example 5 and consider it.
Which of the above methods gives you the quickest idea of how to use this particular function? If you had to figure out how to use this function from an XML parsing library, which level of documentation do you hope the code would have? Explain.
