Re: Re: PEAR software design policy

Thank you both for your advice. > In terms of your assertions "won't affect a lot of people" and "nobody > reads the manual" these sound dangerously like excuses and don't match > any of my experience coding in PEAR :). Any break affects people and > the bug reports happen pretty quickly. Also, I get mails all the time > from people who were looking for an edge case that is documented in the > manual. I didn't say "nobody reads the manual", I said that nobody reads ALL the documentation, and anyway, I wasn't trying to excuse my code exactly, but trying to justify my point that if a function is badly named, a lot of people will not know that it exists because they will skim through the list of functions and not find what they want. For example, which of the following functions returns the 'Julian Day': beginOfMonth beginOfMonthBySpan beginOfNextMonth beginOfNextWeek beginOfPrevMonth beginOfPrevWeek beginOfWeek compareDates dateDiff dateFormat dateNow dateSeason dateToDays dayOfWeek daysInMonth daysToDate defaultCentury endOfMonthBySpan endOfNextMonth endOfPrevMonth endOfWeek firstOfMonthWeekday getCalendarMonth getCalendarWeek getCalendarYear getDay getMonth getMonthAbbrname getMonthFromFullName getMonthFullname getMonthNames getWeekdayAbbrname getWeekdayFullname getWeekDays getYear gregorianToISO isFutureDate isLeapYear isPastDate isValidDate julianDate nextDay nextDayOfWeek nextDayOfWeekOnOrAfter nextWeekday NWeekdayOfMonth prevDay prevDayOfWeek prevDayOfWeekOnOrBefore prevWeekday quarterOfYear weekOfYear weeksInMonth The answer is 'dateToDays()', but wouldn't most users think it was 'getJulianDate()'? This is even more crucial when there isn't much documentation for each function anyway. So dateToDays() is completely useless, because no-one can find it, and no-one knows what it really does. > Thinking about it, some of the commits to Date (I have no knowledge of the > package, just some observations) seem quite ... on the edge of breaking BC, > you are sure you are not removing any public functions that users might have > been using ? :) Well I have changed the behaviour of existing functions when: 1. the old behaviour was obviously a bug 2. the old behaviour was different to what was documented, in which case I changed the behaviour to what was described in the documentation 3. the function was private 4. by adding extra parameters (as Gregory Beaver mentioned) 5. when an invalid parameter is passed - because surely if users call something like setMonth(13) then they can only expect undefined behaviour - after all, they are ignoring the specfication of the function in the documentation. So here I have only modified the undefined behaviour. I haven't removed anything and I will restore the old behaviour as advised. Charles Helgi Þormar Þorbjörnsson <helgith@gmail.com> wrote: On 11/22/07, Gregory Beaver <greg@chiaraquartet.net> wrote: charles woodcock wrote: > Dear All, > > I am currently working on the package 'Date' and I have a couple of > design decisions with which I wanted to comply with the PEAR design > policy: > > There are 3 functions setDay(), setMonth() and setYear() which can be > used to set the individual parts of the date, or the user can set the > date using setDate(), passing in a valid ISO-compatible string. The > current behaviour of setMonth() etc. was to check that the month was > between 1 and 12, and if not, to quietly set the month to 1. > > So if you try to set the date to 31st February then the class allows > you to do this, so I wanted to change the behaviour of setMonth() to > return an exception instead, because this date is obviously not > valid. However it is possible that code exists that calls > setMonth(2) then setDay(28), which would set a valid date, but by > setting the object to a possibly invalid date between the two calls. > > Now should I allow an invalid date like this for the sake of > backwards compatibility, or can I change this behaviour for the > benefit of the users that this will not affect? I would also > provide the function setDayMonthYear() which would allow users to > write equivalent code. I don't think it will affect a lot of people, > and it would be a rare occurrence anyway, but then how strict does > backwards-compatibility have to be? > > My next question is that there is a function getJulianDate() which > returns the day of the year from 1 to 366. But on Wikipedia it says > that the 'Julian Date' is the no of days since Monday, 1st January > 4713 B.C. This behaviour is in fact implemented by the function > Date_Calc::dateToDays() (it does not actually document this fact, and > the function is not valid for years < 0 anyway, but you can take my > word for it). My thinking is that there is no point having all these > functions unless they are well-documented, and even if they are > well-documented, no-one is going to read ALL the documentation. And > a crucial part of the documentation is the function name itself. So > do we have to maintain perpetual backwards-compatibility (by > providing aliases like 'getRealJulianDate()' and leaving the old > functions alone), or is it possible to rename these functions? > > If anybody could help me with this I would be very grateful, Charles Date is version 1.4.7, which means users may be relying upon the odd behavior you've described. Fortunately, there is a way to both preserve BC and provide a better option. You can take one of two possible courses: 1) provide a sub-class of Date that overrides the class to add the behavior you've described, and document it 2) use an option to change the default behavior, set to off by default. In terms of your assertions "won't affect a lot of people" and "nobody reads the manual" these sound dangerously like excuses and don't match any of my experience coding in PEAR :). Any break affects people and the bug reports happen pretty quickly. Also, I get mails all the time from people who were looking for an edge case that is documented in the manual. Thinking about it, some of the commits to Date (I have no knowledge of the package, just some observations) seem quite ... on the edge of breaking BC, you are sure you are not removing any public functions that users might have been using ? :) - Helgi --------------------------------- Which email service gives you unlimited storage?