Development side of the wiki

[jesyspa]

I've been reading through the wiki on development and noticed the following points:

• HackingWesnoth recommends the cplusplus.com tutorial. This is a poor source for beginners. Perhaps suggest Accelerated C++ instead?
• The DevelopersHome page links to the STL documentation. I don't believe Wesnoth actually uses the STL; everything I've seen in the code refers to the standard library. Perhaps refer to cppreference.com?
• The coding quiz still mentions auto_ptr. At the moment, that seems to be used in Wesnoth code somewhat, but it is deprecated and shared_ptr is used much more often.
• The HackingWesnoth pages also links to the STL documentation.
• The coding standards section should probably mention the void A::f() const use-case for const. Perhaps "How does one declare a const member function that takes a const reference to an std::string and returns a pointer to const char?" would make sense, too.

Cheers,
jy

[lipk]

Hello,

HackingWesnoth recommends the cplusplus.com tutorial. This is a poor source for beginners. Perhaps suggest Accelerated C++ instead?

Accelerated C++ is a commercial book, not a tutorial...

The DevelopersHome page links to the STL documentation. I don't believe Wesnoth actually uses the STL; everything I've seen in the code refers to the standard library. Perhaps refer to cppreference.com?

STL and the standard library are the same thing.

The coding quiz still mentions auto_ptr. At the moment, that seems to be used in Wesnoth code somewhat, but it is deprecated and shared_ptr is used much more often.

And of course what is relevant here is what is used within Wesnoth's source.

[Sapient]

I support the OP's suggestions.

The wiki is freely editable, and all you have to do is create a login.

[jesyspa]

Accelerated C++ is not a tutorial, no; unfortunately, most C++ tutorials are of poor quality. learncpp is marginally better, although you'll find that it too does not teach the style that the Wesnoth coding standards advocate. Perhaps the ReelLearning tutorials on YouTube?

The STL is sometimes used as a name for (parts of) the standard library; however, it also refers to the Standard Template Library, which is an old library that the standard library took parts of. The documentation linked to is for the latter; you'll find classes like rope and hash_map there which aren't in the C++ standard library.

Code: Select all

$ grep auto_ptr {,*/,*/*/,*/*/*/}*.{c,h}pp | wc -l
18
$ grep unique_ptr {,*/,*/*/,*/*/*/}*.{c,h}pp | wc -l
19
$ grep shared_ptr {,*/,*/*/,*/*/*/}*.{c,h}pp | wc -l
236
$ grep shared_ptr {,*/,*/*/,*/*/*/}*.{c,h}pp | grep typedef | wc -l
77

This looks like shared_ptr is used much more; is it just in a specific part of the codebase?

[lipk]

Accelerated C++ is not a tutorial, no; unfortunately, most C++ tutorials are of poor quality. learncpp is marginally better, although you'll find that it too does not teach the style that the Wesnoth coding standards advocate. Perhaps the ReelLearning tutorials on YouTube?

*shrugs* I'm not really up-to-date in C++ education material, but I don't think that a commercial product should be advertised on the wiki. (Not as if it mattered in my opinion what is recommended for absolute beginners; C++ is not really a thing that one just learns because he/she happens to need it).

This looks like shared_ptr is used much more; is it just in a specific part of the codebase?

Actually, I haven't checked the usage of any of those classes, but according to your stats, the usage of both are negligible. So, I think, if you want the questions to reflect the state of the code base, that one could be just removed altogether.

[8680]

... the cplusplus.com tutorial ... is a poor source for beginners.

Why? I’d recommend it.

[jesyspa]

In my experience helping newbies on various fora and IRC, those who learn C++ from websites like cplusplus.com show a significantly worse understanding than those who learn from a more comprehensive source. As far as I can tell, this is caused by the order in which things are (and aren't) taught (no standard containers, no RAII, pointers and unions before they are useful), and on the other hand due to a lack of good examples.

Looking at the usages of the typedeffed shared_ptrs, I found 2254 cases. Are you sure it is still best removed? That would leave no RAII question on the quiz as it stands.

[lipk]

Most of the uses cumulate in the whiteboard and AI code, which are rather separated modules. I'm pretty sure that an average Wesnoth developer could get by without knowing about shared_ptr (actually, I haven't seen any in the code I had worked with so far). I won't pretend though that I'm that much interested or qualified in the topic, I just started arguing about it because your original post... err, I apparently misunderstood your original post. I somehow interpreted it in a way that you'd like to replace auto_ptr only because shared_ptr is newer and fancier.

I'm afraid that the above paragraph doesn't make much sense in itself, so I'd like to clarify that my final word is that I don't really care.

[Sapient]

Understanding auto_ptr is a good starting point for understanding exception safety and smart pointers in general. Like many areas of C++, it also has its little hidden pitfalls which are good to know in advance. The fact that we don't use auto_ptr much is irrelevant, IMO.

[jesyspa]

Alright, thanks for the comments; I'll go ahead and perform the suggested changes if there's no further objections. I'll keep the auto_ptr in the question.

[JaMiT]

The DevelopersHome page links to the STL documentation. I don't believe Wesnoth actually uses the STL; everything I've seen in the code refers to the standard library. Perhaps refer to cppreference.com?

Whether you want to call it "STL" or "standard library", Wesnoth does use (fairly often) things covered by that STL documentation, such as iterators, vectors, and maps. So that reference is applicable. Do you have a reason for not linking to the SGI site, other than it not being your personally preferred reference? Removing inapplicable links is one thing, but swapping links based on personal preference might not be such a useful endeavor. (What works for one person does not necessarily work for all people. A priori, using cppreferece,com instead of sgi.com might not end up helping more people than it it hinders.)

[Iris]

Moved to a more appropriate forum.

[jesyspa]

The DevelopersHome page links to the STL documentation. I don't believe Wesnoth actually uses the STL; everything I've seen in the code refers to the standard library. Perhaps refer to cppreference.com?

Whether you want to call it "STL" or "standard library", Wesnoth does use (fairly often) things covered by that STL documentation, such as iterators, vectors, and maps. So that reference is applicable. Do you have a reason for not linking to the SGI site, other than it not being your personally preferred reference? Removing inapplicable links is one thing, but swapping links based on personal preference might not be such a useful endeavor. (What works for one person does not necessarily work for all people. A priori, using cppreferece,com instead of sgi.com might not end up helping more people than it it hinders.)

Because sgi.com does not document the standard library; it documents the STL, which means that there are functions and classes listed there that are not in the standard library (slist, bit_vector, hash_*, rope, sequence_buffer, etc.). It also does not document C functions and iostreams.

[JaMiT]

HackingWesnoth recommends the cplusplus.com tutorial. This is a poor source for beginners. Perhaps suggest Accelerated C++ instead?

I am not particularly fond of removing an online resource in favor of a book. Nor of removing a free resource for one that must be purchased.
(Let me add a little emphasis to "removing". Why remove instead of augment? Too many links is overload, but would an online reference link plus a "buy this book" link be too many?)

Because sgi.com does not document the standard library; it documents the STL, which means that there are functions and classes listed there that are not in the standard library (slist, bit_vector, hash_*, rope, sequence_buffer, etc.).

So? What is the problem with having some documentation for things that are not currently used by the game? As a reference (the DevelopersHome link), it is better to cover too much than too little.

I'll answer that for you. It would be even better to cover exactly what is readily available. However, a link to a general C++ reference still does not cut it. To improve the "Library documentation" links, it would take a link to documentation for the standard library plus a link to Boost documentation (plus other libraries?).

If you want to view the link as a tutorial (the HackingWesnoth link) instead of a reference, I find its presentation to be rather good for introducing its concepts, with a huge amount of carryover to what is used in Wesnoth. I would keep the SGI link on those grounds. Furthermore, are those things not in the standard library forbidden for use in Wesnoth? (There is precedent at least for using hash_* in the form of boost::unordered_*.) Is it bad to learn a little more than is strictly necessary?

It also does not document C functions and iostreams.

Those are much more basic concepts that should be covered by basic C++. Templates are a more advanced topic, one that could easily have been skipped by a basic C++ course/tutorial. The purpose of the link in HackingWesnoth is to highlight the template part of the standard library and to encourage people to use it. A link to a general C++ reference would not have the same effect. I would keep the SGI link on the HackingWesnoth page.

[jesyspa]

Reordering a little so I can answer similar issues together...

Because sgi.com does not document the standard library; it documents the STL, which means that there are functions and classes listed there that are not in the standard library (slist, bit_vector, hash_*, rope, sequence_buffer, etc.).

So? What is the problem with having some documentation for things that are not currently used by the game? As a reference (the DevelopersHome link), it is better to cover too much than too little.

I'll answer that for you. It would be even better to cover exactly what is readily available. However, a link to a general C++ reference still does not cut it. To improve the "Library documentation" links, it would take a link to documentation for the standard library plus a link to Boost documentation (plus other libraries?).

It's not a matter of "currently used", it simply doesn't exist. I agree Boost documentation would be a good addition.

If you want to view the link as a tutorial (the HackingWesnoth link) instead of a reference, I find its presentation to be rather good for introducing its concepts, with a huge amount of carryover to what is used in Wesnoth. I would keep the SGI link on those grounds. Furthermore, are those things not in the standard library forbidden for use in Wesnoth? (There is precedent at least for using hash_* in the form of boost::unordered_*.) Is it bad to learn a little more than is strictly necessary?

It also does not document C functions and iostreams.

Those are much more basic concepts that should be covered by basic C++. Templates are a more advanced topic, one that could easily have been skipped by a basic C++ course/tutorial. The purpose of the link in HackingWesnoth is to highlight the template part of the standard library and to encourage people to use it. A link to a general C++ reference would not have the same effect. I would keep the SGI link on the HackingWesnoth page.

HackingWesnoth recommends the cplusplus.com tutorial. This is a poor source for beginners. Perhaps suggest Accelerated C++ instead?

I am not particularly fond of removing an online resource in favor of a book. Nor of removing a free resource for one that must be purchased.
(Let me add a little emphasis to "removing". Why remove instead of augment? Too many links is overload, but would an online reference link plus a "buy this book" link be too many?)

This is largely the problem with sources like cplusplus.com; a poor explanation of the concepts (including those of the standard library), and very few examples of standard library usage. 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).

You'll find that commonly recommended C++ books (like Accelerated C++) do cover the standard library from early on. My suggestion would indeed be an online reference (cppreference.com currently seeming to be the best choice), and a recommendation of a book (perhaps Thinking in C++; that one's free). Unfortunately, tutorials tend to go into much less depth and skip over these issues.