ios - 我怎样才能改进这个涉及 NSDate 比较的实现？

Question

我是 a calendar library for iOS 的作者，我正在考虑如何改进它，因为很明显人们不理解它。

现在，我有一个只包含一个方法的数据源协议(protocol)，它返回要在给定日期显示的事件:

- (NSArray *)calendarView:(CKCalendarView *)calendarView eventsForDate:(NSDate *)date;

但是，我发现在图书馆可用的两年里，我收到的大部分反馈都是“如何让事件出现在日历上？”

我一直认为它很直观:

1. 创建一些事件。该框架有一个“事件”对象可以使用。
2. 在某些数据源(如字典或核心数据)中按日期对事件进行排序。
3. 在数据源中返回适当的事件对象。

我还能做些什么来让其他开发人员更清楚我打算如何工作？

Answer 1

1. 您的用户想要她可以复制和粘贴然后编辑以解决她的问题的代码。她不想阅读有关接口(interface)的信息，然后从头开始实现它。因此，将 CKCalendarViewDataSource 的玩具实现放在您的文档中。玩具实现需要开箱即用。您的用户应该能够将其粘贴到她的项目中、编译并在日历 View 中查看事件。玩具可以只使用一组硬编码的事件(根据需要调用 [NSDate now] 以确保默认日历月显示事件)。

   我认为在 README 中提供一个工作示例实现最能减轻您的支持难题。

2. 您的用户不想实现回调。她不考虑等待回答问题；她的想法是告诉您的图书馆该做什么。

   将 events 属性添加到 View ，它是 CKCalendarEvent 的数组。让用户设置 events 或 dataSource。在文档和 header 注释中注意，如果有超过几十个事件，您建议使用 dataSource。如果用户同时设置两者，则引发异常。

3. 如果您不断被问到“如何让事件显示在日历上？”然后将该语言放入您的文档中。在您的文档中出现冗余是可以的!文档是为人类准备的，人类需要冗余。

   你可以有很大的部分标题，上面写着“如何将事件添加到日历”、“如何在日历上显示事件”和“如何使事件出现在日历上”，它们都可以说同样的话(最好使用示例代码)或只是链接到“显示事件”部分。

4. 在您的文档中解释，靠近顶部，CKCalendarView 需要一个数据源，就像 UITableView 一样。要明确!你我都认识这种模式，但显然你的用户不认识。

5. 提供更好的数据源接口(interface)。通过 NSDate 查找事件并不是很理想，因为 NSDate 指定的是一个瞬间，而不是一整天。您想要发生在给定日历日的事件，但您不关心事件发生的时间。你是在感兴趣的那一天的午夜吗？如果事件在上午 8 点举行怎么办？更糟糕的是，如果事件发生在第二天凌晨 12:01，并且夏令时从感兴趣的那一天开始怎么办？并非所有的日子都是 86,400 秒!不要让你的用户乱用 NSCalendar；为她做。

   我更喜欢这样的消息:

   - (NSArray *)calendarView:(CKCalendarView *)calendarView
       eventsOnOrAfterDate:(NSDate *)startingDate
       beforeDate:(NSDate *)endingDate;
   

   通过 startingDate 感兴趣日期的午夜 ( or 1 AM on certain days in certain time zones )。 endingDate 为次日午夜。请注意，您应该允许用户指定用于计算这些 NSDate 的日历时区(但默认为 [NSTimeZone systemTimeZone])。

   最好还指定以下消息，以防您的用户按日历日而不是使用精确的时间戳存储她的事件:

   - (NSArray *)calendarView:(CKCalendarView *)calendarView
       eventsForYear:(int)year month:(int)month day:(int)day;