Maybe I'm misreading it, but to me the far more heinous crime than using difficult code (setting aside that it's in the docs) is that the docstring is a total l

Maybe I'm misreading it, but to me the far more heinous crime than using difficult code (setting aside that it's in the docs) is that the docstring is a total lie. """Parses an array of xyz points and returns a array of point dictionaries.""" 'Only, it doesn’t really. It takes an iterable of points...and returns an iterable of 3-tuples of groupped points' The wrongness of it would cause me to double-take, because even if I were familiar with this usage, it isn't what the comment suggests is happening. A docstring more like: """Parses an iterable of values [x,y,z,x,y,z...] and returns an iterable of 3-tuples: [(x,y,z),(x,y,z)...]""" Would be a lot more clear by simple virtue of truth, even if it didn't explain the code step by step.