"Merlijn van Deen" valhallasw@arctus.nl wrote:
Although I appreciate your efforts, I still want to ask you to wait with any other rewrite commits until you have read, understood, and reacted to this (fairly long) email.
All of the points in your email (which I won't quote at length) are very good ones. I think it would be very helpful for all interested participants to agree on style and approach before coding. (My commit this morning, incidentally, was code that I had already written for my own use, which fit in nicely with what Misza had already done. And there's more where that came from, but I'll wait...)
For the coding style, I propose the following:
- As base: PEP 8 [1].
Misza will be disappointed; PEP 8 says to use lowercase with underscores for function and method names. ;)
- Docstrings mandatory, using Epydoc [2] for describing parameters and
return value. Defining the function in this way almost automatically defines unit tests for that function.
This will take some getting used to, but is a very good suggestion.
One module per class
I'd make an exception to this one to allow including subclasses in the same module, such as Page, ImagePage, and Category.
Because adding structure afterwards is much harder, I think we first should decide on what modules/classes we want, then defining what functions we want and what these functions should do. After that, we can start writing unit tests and functions.
Yes, we should have some idea what we want our objects/functions/methods to do and what kinds of values we want them to return before we start writing them!
thirdly: point c. This really is not a seperate point, but it is important. I think we should use the API where possible, but having a fallback to the monobook html parser.
Absolutely. The API doesn't do everything that you can do with HTML (yet), and if we want backwards compatibility we have to remember that the API has changed a lot between MW versions.
On unit testing -- it may be difficult to write unit tests for methods that access the wiki, because the value returned will depend on the contents of the wiki at any given time. Maybe if we have a dedicated test wiki with at least some pages that are locked, so that they give predictable values, that would be a way around the problem.
Russ