Re: PEAR software design policy

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. Thanks, Greg