|
From: Greg G. <gr...@ma...> - 2003-08-23 18:59:41
|
On Tue, 19 Aug 2003, Ken Monks wrote: > These aren't really MAJOR CHANGES (as described in the "Developer's > Etiquette" document), but I have a general question about protocol that I > want to ask before committing these changes, so I am listing them below in > case someone wants to comment. > > I have been in the habit of commenting my changes by surrouning new lines > with > > # KM > : > # END KM > > and commenting out existing lines with > > # DIST (existing line goes here) > > This turns out to be VERY useful to me because I can easily find the lines > that I have changed and can easily revert back to what used to be there when > things don't work as planned. I noticed also that Greg and Gustav have done > similar things in the past, and that has also been helpful in my opionion > since it is more convenient than using diff to compare two revisions of the > file. Clearly we want to eventually remove such commenting before the code > goes into the main AIM distribution, but my question is whether or not we > should commit changes to the develop_2_1 version with such comment lines or > not. > > Personally, I think we should commit such lines except in cases where the > comments would get out of hand, like when searching and replacing something > globally in all files, for example. Then when the develop_2_1 version is > ready to be released, we could just grep out all of the extra comment lines. > The alternative would be for everyone to eliminate any such comment lines > before committing the changes so that no such comments appear in the > develop_2_1 code. How do the rest of you feel about this? I think there is a clear value in doing this where there is a danger that someone not understanding what the old code breaks, puts it back again. Also, if one sees that code is broken, but doesn't understand completely what it was intended to do, it is good practice to comment out the broken lines and maybe add a comment to that effect. Then if something else gets broken by the change, the comments may lead to the `right' solution. On the other hand where a fix is obvious, I think there's no need to include a comment. I have made a comment and added by initials in some cases, e.g. in Aim.mpl I added a StringTools:-RegSub command ... I thought that later readers of the code would wonder what the hell the line was for. I think comments like this are then useful ... and the initials might help another developer track down a further explanation, if needed. > Anyway, here are the changes I've made that I propose to commit: > > Aug 19, 2003 > ------------ > PROPOSAL > I propose to commit the following changes > > * Globally rename Latex to aim/LaTeX as described in previous postings by > Greg Gamble and myself to accomodate Maple 9 (affects 15 files) > > * Minor tweak to `Class/Typefunction` to fix a problem that occurs in Maple > 9 > > * Several changes to Aim.mpl, Util.mpl, aim/Question.mpl and aim/Quiz.mpl to > do the following: > > + Fixed the Mark Summary table so it uses the correct links when the quiz > is focused > > + Removed the focus option from the question toolbars when the Trying a > quiz in aim/Question.mpl (since there is already a "Try Separately" link) > > + Fixed a minor formatting bug in aim/Question.mpl > > + Changed the background color for the teacher's answer and solutions to > make it easier to quickly distinguish between viewing solutions and working > on an active quiz while focusing and unfocusing and reloading quizzes (see > below) > > + Added the aim/HTMLColoredPage method to aim/Util.mpl to allow us to set > the background color for the entire html page. Initially I was going to use > this to distinguish solutions pages from active quiz pages, but it was > overkill. :) Thus this function currently is not used for anything, but I > left it in there in case we decide to add such options in the future. > > + Changed the behavior of AIM with regard to showing solutions as follows: > > The only way for a student to get a new version of a quiz is if he (a) > is attempting the quiz for the first time or (b) requests a new version by > clicking on the New Version link. > > In particular, if the student elects to show solutions to a quiz, he > will continue to see the solutions to the quiz he just completed no matter > what he does until he clicks New Version. This allows a student, for > example, to view solutions on one machine, then switch to a different > machine to print them out (or view some of the solutions, then go for lunch, > and then return and read the rest of them). > > When viewing solutions, the focus option now focuses on the given > question and shows its solution instead of generating a new quiz and > focusing on that newly generated question. This allows a student to print > the solution to just one question instead of printing the solutions to the > entire quiz. All sounds great Ken. I thought for a second that I wouldn't want the change regarding New Version ... but I have to agree the current behaviour has been a nuisance, in a few instances for the reasons you gave. Regards, Greg |
