With iOS 5 there’s a subtle change in behavior related to custom table view headers. Actually it’s just a more strict enforcement of the existing API. But the end result is the same: Your app may not work as you expected when running on iOS 5.

The heightForHeaderInSection method needs to return a height of 0.0 when the viewForHeaderInSection returns a nil for the case when there are no rows in that section. Otherwise you will see a lot of gray, empty header views in your table in iOS 5.

To Apple’s credit they have clearly stated this in the documentation for tableView:viewForHeaderInSection:

This method only works correctly when tableView:heightForHeaderInSection: is also implemented.

But if you missed this in the documentation and you’re wondering why your tables views suddenly don’t look so good in iOS 5, there’s your explanation. And the quick fix.