Talk:Allocator (C++)/GA1

GA Review

Article (edit | visual edit | history) · Article talk (edit | history) · Watch
I've reviewed the article, but I want to get a second opinion from a GAN Mentor to make sure I'm not doing anything wrong as this is my first GAN review -- M2Ys4U ^(talk) 17:09, 21 May 2009 (UTC)

Preliminary review

1. Well-written:

(a) the prose is clear, concise, and understandable to an appropriately broad audience; spelling and grammar are correct; Y

(b) it complies with the Manual of Style guidelines for lead sections, layout, words to watch, fiction, and list incorporation. N

-- I'm worried about the reference implementation, I don't think that that block of code belongs in the article..

2. Verifiable with no original research:

(a) it contains a list of all references (sources of information), presented in accordance with the layout style guideline; Y

(b) reliable sources are cited inline. All content that could reasonably be challenged, except for plot summaries and that which summarizes cited content elsewhere in the article, must be cited no later than the end of the paragraph (or line if the content is not in prose); Y

(c) it contains no original research. N

-- Again the reference implementation is giving me doubts.

3. Broad in its coverage:

(a) it addresses the main aspects of the topic; Y

(b) it stays focused on the topic without going into unnecessary detail (see summary style). Y

4. Neutral: it represents viewpoints fairly and without editorial bias, giving due weight to each. Y
5. Stable: it does not change significantly from day to day because of an ongoing edit war or content dispute. Y
6. Illustrated, if possible, by media such as images, video, or audio:

(a) media are tagged with their copyright statuses, and valid non-free use rationales are provided for non-free content N/A;

(b) media are relevant to the topic, and have suitable captions N/A.

-- M2Ys4U ^(talk) 17:09, 21 May 2009 (UTC)

Hi, thanks for your review. The concern about source code and original research is a valid one, and it's a question that does pop up from time to time. See for instance this fairly recent discussion here: Wikipedia_talk:WikiProject_Computer_science/Archive_8#Source_code_written_by_editors. In a shameless appeal to authority, I very much agree with how professor David Eppstein puts it:

...my position is that, as code snippets are used here, they are not significantly different from writing prose, or maybe more like writing chemical formulas or mathematical equations: they are a way of expressing ideas for other people to read, in a language that is more precise than English. We don't forbid people to write a mathematical formula unless that formula has already appeared in a reliable source. We don't forbid people to write an English sentence unless that sentence has already appeared in a reliable source (in fact, it's the opposite, we prefer not to plagiarize). By the same token we should not forbid people from writing code snippets that do not come from other sources.

My personal opinion is that this example can be more or less derived from the standard's requirements and the interface of the default allocator. There's not that many ways to skin this particular cat. It is also extremely similar to [1] and could probably be sourced to that. However, that example is flawed in that the template may not be instantiated with void. I could even provide inline citations for the individual parts of the example. The typedefs and general interface from the standard, the void specialization from Meyers (IIRC), and the 10-12 lines of actual code to Austern, with only minor corrections.

Yes, overuse of self-published source code examples is bad, but I really feel that an article on a programming concept needs to have a minimal example (and this one really is minimal). I would even go so far as to say it is essential. decltype (talk) 18:01, 21 May 2009 (UTC)

Second opinion

I've been asked by M2Ys4U to look over this review. The article is well-referenced, seems comprehensive (to one who knows little about the subject!), and is certainly not far off GA standards - congratulations to its author(s). The issues I spotted that may need addressing are listed below:

• The lead, per WP:LEAD, should be a summary of the article. While this is true to some extent, I think it might be expanded slightly to give a more in-depth overview.
• WP:MTAA: we are asked to make technical articles as accessible as possible to a general audience. Often the best place to do this is in the lead so the lay-reader can come away with at least a grasp of what the subject is about and why it's important (even if they can't follow later sections which may become necessarily technical). For example, the first sentence of the article lost me - what are objects, memory allocation and deallocation, and primitives? Even though some of these are linked, some explanation would be helpful. WP:JARGON might also be useful in addressing this.
• Why was Stepanov asked to provide "a library mechanism for abstracting different underlying memory models"? Was there a problem to be solved? (and can we de-jargonise the sentence?)
• I share some of the reviewer's concerns about WP:OR and WP:NOTTEXTBOOK relating to the long code snippets - these may be best left for the external links. However, the author makes a spirited defence, so I've requested further input at WT:GAN#Third opinion requested.
• What makes ddj.com a reliable reference?

Well done on a fascinating article, and thanks to M2Ys4U for a good first review. I hope we can get these points sorted; I will defer to M2Ys4U's judgement (as the primary reviewer) on the progress of the review. All the best, EyeSerene^talk 09:01, 26 May 2009 (UTC)

Thanks for giving your input. It is certainly not easy to make an article like this accessible to a general audience, but that said, I have not been focusing enough on this from the start (It was brought to my attention by an {{expert-subject}} tag). Trying to improve the lead with this in mind shall be my main priority.

As for the source code, I am afraid I am going to have to stick to my "spirited defense" :). I am going to insist on the minimal examples being kept even if it means failing GA status, because I feel that the article would otherwise be a huge letdown for anyone with some background knowledge. If I can write a sentence in English without citing a source, why can't I write an expression in C++ (a more precise language) without citing a source? (That is, for material unlikely to be challenged)

ddj.com is the web portal of Dr. Dobb's Journal, arguably the most respected print magazine for C++ programmers, or even programmers in general. decltype (talk) 09:31, 26 May 2009 (UTC)

Thanks for your responses. The lead is looking much better, though I think it's still beyond our "intelligent 12-year old" target reader level. In some respects that's a function of the type of article, and the best we may be able to aim for is that the casual reader comes away with an idea of what allocators do and why they're significant. The picture is a nice addition (though not required for GA), and its license etc pass muster. I'm happy to accept your assurance re ddj.com; it looked fine when I visited the site, but I wanted to be sure it was a recognised and established publication.

Given the other opinions at WT:GA, the sticking point may be the code examples; the objection is that Wikipedia is not a how-to manual, so while we can describe what allocators are, their development, and their purpose, we aren't supposed to explain (beyond basic syntax) how to use them. I appreciate that without these examples you feel the article is incomplete, but as I mention above this is the purpose of the external links section - readers can be directed off-site for this sort of thing. We may have to respectfully agree to disagree on this, so the ultimate decision is yours. Irregardless, thank you for submitting the article to GAN, and I hope you feel it has been improved as a result. All the best, EyeSerene^talk 07:44, 27 May 2009 (UTC)

Thanks again for your thoughtful and constructive comments. I am glad that you acknowledge (at least to some extent) that a casual reader may not learn much from the article. Mayer–Vietoris sequence comes to mind again. Except for Terence Tao and the like, I have a feeling most 12-year olds would have a hard time with that one. But in general, I do agree that we should trystrive to make our articles as accessible as possible. It's just so incredibly difficult.

The only thing I strongly disagree with, is that "the ultimate decision is [mine]". It's respectful of you to say that, but it's simply not true. If anyone were to remove the example per WP:OR, I feel that I wouldn't have much of a case anymore. decltype (talk) 08:28, 27 May 2009 (UTC)

The article is looking better every time I check back - not surprising given the amount of work that's been going into it. I see the code has gone (I appreciate your point about ownership, but all the same as a reviewer I would have been uncomfortable making a change that substantial myself). The technical aspect is much improved too, though I'd still like to see a brief 'layman's terms' sentence or two near the start; although you've wililinked everything relevant, my personal opinion is that it's best not to encourage the reader too enthusiastically to browse straight back out of an article they've just browsed into ;) Maybe as the second sentence of the lead, something like "The C++ programming language uses allocators to automatically assign sections of the computer's memory to the various functions of a program."? I'm sure you can improve on that, but hopefully it serves to illustrate my point. EyeSerene^talk 19:16, 28 May 2009 (UTC)

[outdent] Yes, I decided to move the code to the talk page, based on three things

• The OR concerns raised.
• Austern's example does in fact handle the allocator<void> case correctly. I misread it.
• Within article space the code would technically be licensed under the GFDL, which would prevent commercial use in many cases.

I believe that what you would like to see is a sentence which establishes context without going into other features, like containers, but it's not easy. Because, to be honest, allocators are not a vitally important concept of C++, and they only come into play if you utilize certain parts of the library. Stepanov didn't even consider them an essential part of his library ("Allocators, however, are not essential to STL ..."). In fact, from my experience, many developers with many years of C++ working experience are completely oblivious of allocators. But I am going to try hard to come up with something. decltype (talk) 06:20, 29 May 2009 (UTC)

That's roughly what I'm getting at, yes. I don't have a problem with mentioning the other features, but to avoid the impression of 'industry-speak', possibly not by name so early in the lead (for example, could we use "data structures such as arrays or lists" instead of "containers"?) Incidentally, I really appreciate the patience you're showing over this; it's a pleasure to encounter such a collaborative and dedicated editor! All the best, EyeSerene^talk 16:43, 29 May 2009 (UTC)

Likewise. I find your personable demeanour and the way in which you constructively criticize very inspiring. I have tried to simplify the lede once more, but there's this little pedant on my shoulder who keeps insisting that everything needs to be 100% technically correct as well, and he simply won't shut up. decltype (talk) 12:54, 30 May 2009 (UTC)

Heh, that's a good thing - there's a world of difference between simplifying and dumbing-down ;) Your latest incarnation of the lead is excellent and supplies an accessible context for the rest of the article. I believe you've now satisfactorily addressed all the points I raised above, and I have no objections to this article being listed as a GA. I'll leave a note for the original reviewer. It's been a pleasure working with you, and thank you once again for your hard work. All the best, EyeSerene^talk 15:01, 30 May 2009 (UTC)

Let me say as well that I've been very impressed with the changes made to this article during the course of this review, especially to the lead. It's become a very nice little piece of work, so well done to everyone. --Malleus Fatuorum 16:46, 30 May 2009 (UTC)

I've passed the article, well done guys :) I've learned a lot from (attempting to) review this article, and the article has been improved hugely. -- M2Ys4U ^(talk) 16:57, 30 May 2009 (UTC)

Thanks everyone for your comments, all of which led to improvements. It's no secret that different reviewers have different standards. Considering the amount of people who have given their input on this article, I have at least some confidence that it deserves to be listed. decltype (talk) 17:13, 30 May 2009 (UTC)

Well deserved. Congratulations ;) EyeSerene^talk 17:35, 30 May 2009 (UTC)