API talk:Client code/Gold standard

[Moved from API talk:Client code --Fhocutt (talk) 16:03, 3 June 2014 (UTC)

Comments

Please leave comments on other features of a great API client library that are missing here, or any criteria above that you do not think are essential/reasonable. --Fhocutt (talk) 06:43, 23 May 2014 (UTC)

From IRC chat with Mithrandir:

• consider packaging for distros?
  • Way beyond gold standard, probably beyond platinum
• consider MSI for Windows? (not common)
• "it should be easy to get help with the library, via lists, irc or forums"
  • ...with some form of enforced community standards? i.e. friendly space/code of conduct/similar. Not currently something any of these have to my knowledge but I'd like to see it. --FH
  • Something like Rust's: http://www.reddit.com/r/rust/comments/1nvsdh/a_note_on_conduct_please_read/
• have a "gold standard" and "platinum standard" list, moving items to "gold standard" as libraries get there
  • possibly a pie-in-the-sky list
• easy to use => "uses language idioms"
• maybe quantify "reasonable length of time", maybe not--"a couple of weeks" perhaps, which is not "a month" to most people
  • is there an established way to deal with this?
• complete coverage for unit tests is a high and sometimes-pointless bar
  • find out best QA practices and require those
  • something more like "all MW API functions' functions have tests"? "all real functions" (needs better phrasing)/more precise phrasing for "reasonable test coverage" <--- consider the reason for the standard?

• it would be pie-in-the-sky amazing if the client lib maintainers actually had contacted us in the past for any reason, I think --sumanah
• handles wikidata/wikibase functions: platinum/pie-in-the-sky

Compatibility

I expect a library to take care of the compatibility with API versions. Concrete example: [1]. I want to tell the library: give me all these info from meta=siteinfo, if possible. I don't want to dig docs and release notes to hardcode in my client a series of release checks and switches for each relase to avoid fatal errors.

WikiTeam an exacting use case, but we can do without "Easy to install" "Easy to use", "Easy to debug", "Easy to improve" (everything but "Well designed" bullet); I think we'd decide exclusively depending on the point above. So I hope it makes to the standard or you can give me some advice on which libraries satisfy those requirements. --Nemo 19:21, 25 June 2014 (UTC)

Nemo, most of the libraries I've looked at appear to prioritize staying up to date with new versions of MediaWiki over maintaining compatibility with old ones. The Java Wiki Bot Framework has tests for versions in site info back to v1.15,[2] but I'm not aware of any other client libraries that explicitly handle old MediaWiki versions. Sorry for the delayed reply, and that I haven't found anything that suits WikiTeam's needs. --Fhocutt (talk) 01:51, 2 August 2014 (UTC)

I agree with Nemo. The gold standard should articulate the level of compatibility expected from libraries. The library documentation should at least describe how it behaves on various MW versions that are known to exist. At the very least, 'Gold standard' should require that the library supports all supported versions of MW, including supported by the MW devs or by any major vendor. John Vandenberg (talk) 07:15, 11 September 2014 (UTC)

Code is commented and readable

When you feel the need to write a comment, first try to refactor the code so that any comment becomes superfluous. -- Marin Fowler, Refactoring: Improving the Design of Existing Code, 1999

If your code is readable, then why would you need comments? This alone makes me highly dubious of how readability of code is being evaluated. --Jeroen De Dauw (talk) 23:30, 10 July 2014 (UTC)

@Jeroen De Dauw: Hi there Jeroen! Thanks for commenting on this. (I've taken the liberty of formatting the Fowler quote.)

So, in Making Software: What Really Works, and Why We Believe It (ed. Oram & Wilson, 2010), researchers found that the type of information that developers most frequently sought and could not find in a codebase was the *design rationale*. Why did the developer make these implementation choices? as a workaround? to fix a particular bug? in a hurry? for performance reasons? for backwards compatibility? One place to put that information is in code comments. See the "easy to debug" section of the standard: "Terrible hacks/instances of extreme cleverness are clearly marked as such in comments".

I agree that, in the long run, often code with comments is a candidate for refactoring, especially if the comments explain *what* is being done rather than *why*. But this standard is something to use to evaluate these libraries as they are now, in the short run, and suggest areas for improvement. Code comments are part of how many developers understand each other's work, and are generally useful. We use comments on the MediaWiki codebase as well, after all. :)

It sounds like you're happy with the other criteria in the gold standard, which is great to hear. Thanks! Sharihareswara (WMF) (talk) 01:44, 12 July 2014 (UTC)