Development side of the wiki

[JaMiT]

It's not a matter of "currently used", it simply doesn't exist.

Huh? Does the SGI STL download page exist only in my imagination? (Not to mention that projects like STLport have continued the work that SGI abandoned.)

Besides, of the five examples you gave:
* slist -- exists in Boost.Container. ("Just" requires upping the minimum required Boost version to 1.48.)
* bit_vector -- documented by SGI as being deprecated, just without using the word "deprecated". So no reason to think this should be used instead of vector<bool>.
* hash_* -- currently in use in Wesnoth in the form of Boost's unordered_* templates.
* rope -- I don't really see Wesnoth ever handling the type of text that would make this class worthwhile, but if it did, using ropes might be a good idea.
* sequence_buffer -- documented by SGI as being useless if you are not using ropes. I would consider this part of ropes, not a separate concept.

In summary, two are available via Boost, one is deprecated (so might as well not exist), and one (the rope/sequence_buffer combo) is unlikely to be useful (so existing does not make a real difference). A little extraneous information does not hurt -- particularly when it is so easy to see that it is extraneous -- and better to have a little extra information available than too little.

I know that two or three years ago, when I was actively reading cplusplus.com, most of the questions on the quiz simply sounded like gibberish to me because the tutorial does not mention vectors, iterators, or copy-constructors (as far as I can tell at a glance).

Tutorials are not designed for glancing; they are intended for reading. Trying to take a shortcut (looking up just the answers to those specific questions) is trying to avoid learning, which at best leaves huge gaps in what you should know. In other words, you should have read the entire tutorial in your effort to make sense of the gibberish-sounding parts of the quiz. If you could simply get the answers to the quiz questions, sure you could pass the quiz, but you would still not have the knowledge needed to effectively hack Wesnoth.

(The above is assuming you were just a beginner since you followed the "beginners" link instead of the "knowledgeable programmers" link. A knowledgeable programmer could potentially just need a reference to look up the words in those specific questions since the gaps could be filled by pre-existing knowledge.)

And for the record, the cplusplus.com tutorial does not cover vectors and iterators because those are advanced topics relegated to cplusplus.com's library reference (the link called "STL: Standard Template Library"). Copy constructors are covered by the tutorial, just not in a section of their own -- they are mentioned toward the end of the subsection on default constructors.

Unfortunately, tutorials tend to go into much less depth and skip over these issues.

That is kind of the point of a tutorial. A tutorial sacrifices depth in favor of explanations. An instruction book sacrifices explanations for depth. It is tough (not necessarily impossible, but very tough at least) to have both the explanations of a tutorial and the depth of an instruction manual, while managing to not turn off all readers in the process. Keep in mind what the contexts of those links. Are the links supposed to be tutorials for those getting started, are they instructional for those who have already advanced past the tutorials, or are they references where you look up specific details?

[jesyspa]

Huh? Does the SGI STL download page exist only in my imagination? (Not to mention that projects like STLport have continued the work that SGI abandoned.)

The download page exists; however, that's not the library used when building Wesnoth. If you are using things provided by boost, why not link to boost's documentation on it? I simply don't see the logic behind linking to the documentation of a library (no matter how similar) that one does not use, especially seeing as the pages all imply that it is used.

I know that two or three years ago, when I was actively reading cplusplus.com, most of the questions on the quiz simply sounded like gibberish to me because the tutorial does not mention vectors, iterators, or copy-constructors (as far as I can tell at a glance).

Tutorials are not designed for glancing; they are intended for reading. Trying to take a shortcut (looking up just the answers to those specific questions) is trying to avoid learning, which at best leaves huge gaps in what you should know. In other words, you should have read the entire tutorial in your effort to make sense of the gibberish-sounding parts of the quiz. If you could simply get the answers to the quiz questions, sure you could pass the quiz, but you would still not have the knowledge needed to effectively hack Wesnoth.

And for the record, the cplusplus.com tutorial does not cover vectors and iterators because those are advanced topics relegated to cplusplus.com's library reference (the link called "STL: Standard Template Library"). Copy constructors are covered by the tutorial, just not in a section of their own -- they are mentioned toward the end of the subsection on default constructors.

Sorry for the confusion; I was, at the time, following the C++ tutorial thoroughly; the "at a glance" referred to what I could judge now.

The problem is that iterators are not advanced concepts, and vectors even less so; they're significantly simpler both to explain and to use than pointers. Moreover, they should generally be preferred over pointers + operator new, yet the tutorial entirely fails to mention this.

You are right, the copy constructor is mentioned in the "default constructor" section. Which fails to mention common cases such as the rule-of-three and checking for self-assignment; moreover, it does not provide a use case for where one would want to use a copy-constructor.

Unfortunately, tutorials tend to go into much less depth and skip over these issues.

That is kind of the point of a tutorial. A tutorial sacrifices depth in favor of explanations. An instruction book sacrifices explanations for depth. It is tough (not necessarily impossible, but very tough at least) to have both the explanations of a tutorial and the depth of an instruction manual, while managing to not turn off all readers in the process. Keep in mind what the contexts of those links. Are the links supposed to be tutorials for those getting started, are they instructional for those who have already advanced past the tutorials, or are they references where you look up specific details?

That'd be great if the cplusplus.com tutorial was meant as a first-day introduction from which people would move on to more advanced sites for any non-trivial matters. It isn't; the tutorial clearly states

These tutorials explain the C++ language from its basics up to the newest features of ANSI-C++, including basic concepts such as arrays or classes and advanced concepts such as polymorphism or templates.

and this is how it is often treated. If there was not a qualitative difference between people learning from places like cplusplus.com and people learning from better sources, I would not be bothering with this discussion; however, as a prolonged visit to ##c++-basic on Freenode, or /r/learnprogramming on Reddit, or any other place where beginners hang out will show you, the gaps in understanding are very significant. (Yes, this is all taking into account that these people are newbies.)

[JaMiT]

The download page exists; however, that's not the library used when building Wesnoth.

Exactly. It is not used when building Wesnoth. Currently. The build requirements can be changed if needed. The library does exist, and the matter is one of "currently used".

If you are using things provided by boost, why not link to boost's documentation on it?

Depends on which SGI link you are talking about. For the one on the HackingWesnoth page, I would say it's because the SGI site does a much better job of explaining the concepts. For the one on the library documentation page, I already stated that I think it would be improved if the SGI link was replaced by a link to a standard library reference plus a link to Boost. (In fact, I think it's about time Boost got a link there. I'll leave the SGI link for now.)

Sorry for the confusion; I was, at the time, following the C++ tutorial thoroughly; the "at a glance" referred to what I could judge now.

Ah, I see.

The problem is that iterators are not advanced concepts, and vectors even less so; they're significantly simpler both to explain and to use than pointers.

Well, I disagree about the simpler to explain and use, but that is more a matter of opinion. On the other hand, they are objectively advanced concepts. Pointers and arrays are intrinsic to the language, while iterators and vectors are provided by libraries. That alone makes iterators and vectors more advanced than pointers and vectors, particularly when you consider that iterators and vectors do not add much functionality beyond what pointers and arrays provide. (There is more convenience for many tasks, but the basic functionality is similar.)

Now you can argue that parts of the STL should be taught instead of basic language functionality, but that does not mean the people writing tutorials are going to agree with that.

That'd be great if the cplusplus.com tutorial was meant as a first-day introduction from which people would move on to more advanced sites for any non-trivial matters. It isn't; the tutorial clearly states

These tutorials explain the C++ language from its basics up to the newest features of ANSI-C++, including basic concepts such as arrays or classes and advanced concepts such as polymorphism or templates.

and this is how it is often treated.

I do not see the contradiction here. The tutorials explain the C++ language from the basics to polymorphism and templates. There is no claim that they explain the language in its entirety. (There is an implication to that effect, but read the quote carefully. A phrase like "including advanced concepts" is not the same as "including the most advanced concepts". If others are treating it as more than it is, perhaps those others are mislead.) Once people are done with the tutorials, they can (perhaps should) move on to more advanced sites or books.

If there was not a qualitative difference between people learning from places like cplusplus.com and people learning from better sources, I would not be bothering with this discussion;

You say "like cplusplus.com". So not just cplusplus.com. Are you comparing the self-taught to those who took classes? Or more along the lines of self-taught online versus self-taught from books? (In either of these case, there is a possibility that you are not seeing cause-and-effect, but rather two effects of the same cause -- perhaps the type of person who would seek out an online tutorial to learn from is also the type of person who would have difficulty understanding the concepts regardless of how they were taught.)

That's not supposed to invalidate your conclusion, but question what can be learned from your observations. There could be more going on than you realize. It's not cplusplus.com specifically that I would like to keep a link to, but a link to an online resource. Do your informal observations indicate that such a link would do more harm than good?

[jesyspa]

The problem is that iterators are not advanced concepts, and vectors even less so; they're significantly simpler both to explain and to use than pointers.

Well, I disagree about the simpler to explain and use, but that is more a matter of opinion. On the other hand, they are objectively advanced concepts. Pointers and arrays are intrinsic to the language, while iterators and vectors are provided by libraries. That alone makes iterators and vectors more advanced than pointers and vectors, particularly when you consider that iterators and vectors do not add much functionality beyond what pointers and arrays provide. (There is more convenience for many tasks, but the basic functionality is similar.)

Now you can argue that parts of the STL should be taught instead of basic language functionality, but that does not mean the people writing tutorials are going to agree with that.

Substitute "advanced" with "complex", then. A good explanation on vectors is easier to write than a good explanation of pointers and dynamic memory management (even without exceptions taken into account; I've had to give both several times). If I have time, I'll write up both and post them here for comparison.

I do not see the contradiction here. The tutorials explain the C++ language from the basics to polymorphism and templates. There is no claim that they explain the language in its entirety. (There is an implication to that effect, but read the quote carefully. A phrase like "including advanced concepts" is not the same as "including the most advanced concepts". If others are treating it as more than it is, perhaps those others are mislead.) Once people are done with the tutorials, they can (perhaps should) move on to more advanced sites or books.

If there was not a qualitative difference between people learning from places like cplusplus.com and people learning from better sources, I would not be bothering with this discussion;

You say "like cplusplus.com". So not just cplusplus.com. Are you comparing the self-taught to those who took classes? Or more along the lines of self-taught online versus self-taught from books? (In either of these case, there is a possibility that you are not seeing cause-and-effect, but rather two effects of the same cause -- perhaps the type of person who would seek out an online tutorial to learn from is also the type of person who would have difficulty understanding the concepts regardless of how they were taught.)

That's not supposed to invalidate your conclusion, but question what can be learned from your observations. There could be more going on than you realize. It's not cplusplus.com specifically that I would like to keep a link to, but a link to an online resource. Do your informal observations indicate that such a link would do more harm than good?

No, cplusplus.com is not the only offender; thenewboston and antiRTFM are commonly recommended examples that suffer from similar problems.

Tutorials generally do not give one a feeling of what the language is about. Very often, they show bits and pieces of syntax without actually ever showing how these features fits together in the big picture, or why these have been added. C++ is a big language, and it can be taught both top-down and bottom-up. These tutorials attempt the bottom-up approach and fail: they only do the "bottom" part. While language constructs are covered, the next step is never taken: most notably, constructors and destructors are never used to make RAII.

Furthermore, while there could be a common cause, most people do understand these concepts better with further explanation. Pointers are the most common case where this happens; even if they understand the syntax thoroughly, people still have no idea why they would use pointers. Or templates. Or polymorphism. Or classes. Or functions. That a function shouldn't be seen as just a name for a few statements may seem obvious, but it isn't to a newbie, which is where code full of global variables and void() functions comes from.

The best online resource I am aware of is Thinking in C++. There are also Stanford Lectures available on YouTube. While cplusplus.com is the top Google result when searching for "c++ tutorial", I doubt linking to it is going to change anything; however, I also don't think the link will help anyone who seriously wants to learn C++ or contribute to Wesnoth development.

[JaMiT]

These tutorials attempt the bottom-up approach and fail: they only do the "bottom" part. While language constructs are covered, the next step is never taken: most notably, constructors and destructors are never used to make RAII.

Furthermore, while there could be a common cause, most people do understand these concepts better with further explanation. Pointers are the most common case where this happens; even if they understand the syntax thoroughly, people still have no idea why they would use pointers. Or templates. Or polymorphism. Or classes. Or functions. That a function shouldn't be seen as just a name for a few statements may seem obvious, but it isn't to a newbie, which is where code full of global variables and void() functions comes from.

Well, these are general programming (or general object-oriented programming) concepts. They are not really part of the C++ language. The people who need to learn these things need more than just a tutorial on a language; they need a tutorial on programming. A good tutorial on programming would need to include a (possibly brief) tutorial on a programming language (so examples can be given), but a good tutorial for a language does not need to include a tutorial on programming. I would not say these tutorials "attempt the bottom-up approach and fail". Rather I would say they only attempt to cover the "bottom" part because what you see as the "top" part transcends the language.

How I viewed those links are links to language tutorials for people who already know something about programming ("beginner programmer", not "non-programmer"). Sure, they are woefully inadequate for brand new programmers. If those links are intended for someone with no programming experience, they should be replaced. So is the intent to have links for beginner programmers or for non-programmers looking to start programming? (Or should there be three links -- one for knowledgeable programmers, one for beginner programmers, and one for new programmers?)

[jesyspa]

Well, these are general programming (or general object-oriented programming) concepts. They are not really part of the C++ language. The people who need to learn these things need more than just a tutorial on a language; they need a tutorial on programming. A good tutorial on programming would need to include a (possibly brief) tutorial on a programming language (so examples can be given), but a good tutorial for a language does not need to include a tutorial on programming. I would not say these tutorials "attempt the bottom-up approach and fail". Rather I would say they only attempt to cover the "bottom" part because what you see as the "top" part transcends the language.

How I viewed those links are links to language tutorials for people who already know something about programming ("beginner programmer", not "non-programmer"). Sure, they are woefully inadequate for brand new programmers. If those links are intended for someone with no programming experience, they should be replaced. So is the intent to have links for beginner programmers or for non-programmers looking to start programming? (Or should there be three links -- one for knowledgeable programmers, one for beginner programmers, and one for new programmers?)

If you look at the first few pages of the tutorial, it is clear that it is written expecting no prior programming knowledge; otherwise, explaining variables at the detail level at which they are explained would make little sense, while explaining the (language-specific) distinction between declaration and definition would be most useful. (Note that the section on constants gets that outright wrong.) Looking further, the tutorial fails to mention such basic facts as that void f(int arr[]) is actually just void f(int* arr), as well as some rather nasty rules involving unions. If a tutorial focusing purely on the C++ language is desired then there's the C++ annotations that get that just right; however, they obviously require more programming experience (as mentioned in the Wiki).

If little or no programming experience is expected, then dumping C++ onto someone and expecting them to figure out programming principles on their own is just cruel. Beginner programmers, just like non-programmers, need some degree of guiding to understand the purpose of features they've not yet encountered; they may find the first few pages to be too verbose, but that tends to end by the time pointers or classes are reached.

To summarise: In my experience, learning the language features without also learning some of these things that transcend the language simply leads to misunderstandings of the language features. On the other hand, a tutorial intended for those who know the transcended features can and should refer to them to give the language features better context. The aforementioned tutorials do neither.

I've written up the aforementioned comparison between teaching vectors and teaching operator new[] using two common cases; comments are welcome.

[JaMiT]

If you look at the first few pages of the tutorial, it is clear that it is written expecting no prior programming knowledge; otherwise, explaining variables at the detail level at which they are explained would make little sense, while explaining the (language-specific) distinction between declaration and definition would be most useful.

Explaining variables in detail makes sense to me, when I think about people coming from other programming languages. That explanation does start at a fairly basic level, but I can see that being easier than trying to determine what exactly the least common denominator is amongst all languages. As for the distinction between declaration and definition, why would that explanation be so useful? That tutorial is itself a demonstration that one can go some distance without the need to separate the two. I'd agree a section on header files would be useful, but "most" useful?

If little or no programming experience is expected, then dumping C++ onto someone and expecting them to figure out programming principles on their own is just cruel.

Perhaps that is why I assumed those links were for beginner programmers, rather than non-programmers? For someone who has had exposure to programming concepts, but lacks experience with non-toy programs? Are you suggesting we add a disclaimer warning those with no programming knowledge against trying to teach themselves programming and C++ at the same time?

I've written up the aforementioned comparison between teaching vectors and teaching operator new[] using two common cases; comments are welcome.

Those links lead to almost-empty pages for me (just some "waiting" graphic in the center). However, based on their names, I do have a suggestion. Teaching operator new[] means going into memory management, which could be a reason why you think arrays are the more difficult concept. Have you considered writing a tutorial on arrays and pointers without going into dynamic memory allocation? That would be more comparable to a tutorial on vectors and iterators.

Also, your first tutorial focuses on vectors, rather than iterators? That would suggest it covers only random-access iterators. It might be a fairer comparison to learning pointers if the tutorial covered all types of iterators. (The number of types of iterators is one reason I find them to be a more complex topic than pointers.) I suppose, though, that if you decide vectors are the only containers worth mentioning in your tutorial, then it might not be necessary to do more than mention that other types of iterators exist.

When I disagreed about the ease of explaining iterators and vectors versus pointers and arrays, I was thinking along this more equitable comparison: covering the various iterator concepts versus covering the various pointer concepts; comparing vectors allocated on the stack versus arrays allocated on the stack. When covering pointers, it would be appropriate to mention that dynamic allocation is possible, but that would be another, separate topic. (Discussing memory management requires some knowledge of pointers, but using pointers does not require any sort of memory management.)

[jesyspa]

Explaining variables in detail makes sense to me, when I think about people coming from other programming languages. That explanation does start at a fairly basic level, but I can see that being easier than trying to determine what exactly the least common denominator is amongst all languages. As for the distinction between declaration and definition, why would that explanation be so useful? That tutorial is itself a demonstration that one can go some distance without the need to separate the two. I'd agree a section on header files would be useful, but "most" useful?

I'm pointing out these issues because these are the ones I most see people struggle with; both people with and without prior programming experience.

Perhaps that is why I assumed those links were for beginner programmers, rather than non-programmers? For someone who has had exposure to programming concepts, but lacks experience with non-toy programs? Are you suggesting we add a disclaimer warning those with no programming knowledge against trying to teach themselves programming and C++ at the same time?

Again, you overestimate beginner programmers. Those familiar with another language are not immune to these issues.

Those links lead to almost-empty pages for me (just some "waiting" graphic in the center). However, based on their names, I do have a suggestion. Teaching operator new[] means going into memory management, which could be a reason why you think arrays are the more difficult concept. Have you considered writing a tutorial on arrays and pointers without going into dynamic memory allocation? That would be more comparable to a tutorial on vectors and iterators.

I have done my best to minimize how much focus is on memory allocation, and generally tried to solve each problem as simply as possible. I didn't get into iterators, nor into arrays (but then, I don't intend to ever teach raw array passing semantics; it's frustrating and unrewarding).

Also, your first tutorial focuses on vectors, rather than iterators? That would suggest it covers only random-access iterators. It might be a fairer comparison to learning pointers if the tutorial covered all types of iterators. (The number of types of iterators is one reason I find them to be a more complex topic than pointers.) I suppose, though, that if you decide vectors are the only containers worth mentioning in your tutorial, then it might not be necessary to do more than mention that other types of iterators exist.

It does not cover iterators at all. It does not explicitly consider arithmetic on pointers either, so I think that is fair. I have the opposite view: the various iterator types can be taught separately with motivation for each. However, that is a much larger topic (and again, a rather neglected one by tutorials). I would definitely not teach it as part of teaching containers, as it brings more confusion than understanding there. (Nor would I explicitly teach pointer arithmetic until I had no other choice.)