| The following is a working draft of guidelines for writing the tutorials. Please discuss below to improve the guidelines:
I've put up some content to try out things a bit. This should make the discussions about the C++ book more productive. Also, it can be a good starting point.
Note: the current content is only a sketch. It does have major flaws. If you think it can be improved, just edit it, or open a discussion here if you're unsure.
I've spent some time thinking about the issues raised and the solutions proposed in the discussion that followed the initial proposal. One thing is clear: most of the problems can be solved by not having a rigid structure. We should strive for as much flexibility as possible. A good way to achieve this is to have a lot of small, independent items, that we can later rearrange as we want without much effort. This requirement is covered by the following points, which could serve as a starting point of our guidelines after improvements:
- The content is divided into independent, self-contained items. The basic criteria is as follows: it must be possible to move the item to a separate page without impacting its quality much.
- Each item has a very limited scope.
- A single article may contain several items that have similar scope. In some cases this may improve navigation quite a bit.
- Since there are no warranties that the structure of the wiki will be retained in the future, all items must provide an easy way to get a link to the item though some redirect wrapper, which can be updated in the case item is moved to another page. (This point will be made more concrete when we have such redirect wrapper).
If the above guidelines are met, the high-level structure of the book could be changed on the whim just by rearranging the items in the main page (or in any summary pages). This means that the process of writing tutorials is simplified a lot: one is concerned only with the scope-limited item he's writing now, not the overall structure. Also, we don't need to "design" the structure of the wiki from the start, given that better decisions can be made once the content is available.
The current sketch is divided into two sections: an introduction and the rest of content. The purpose of the introduction is to explain C++ to the readers that have little if any programming experience in C++. This will allow to assume that the reader at least knows the basics in the rest of the wiki, so that we can explain all the peculiarities of one feature or another, without worrying that, e.g. a detailed article about variable scope is read by a reader who doesn't know what a function is.
It won't be possible to easily rearrange the introduction section due to its purpose, but I think that's not a big problem, since the bulk of the content and effort will go to the rest of the wiki.
I think we can start filling in the tutorials in the introduction section. This should reveal any issues with the current approach and allow us to refine the guidelines.
--P12 04:22, 12 September 2013 (PDT)
The main page
Should we have a link to each article in the main page? This will improve discoverability. Since the readers can be assumed to come here to learn something, not to solve a specific issue, we don't need to keep the main page short. But maybe someone knows other reasons for limiting the size of the main page? --P12 04:42, 12 September 2013 (PDT)
- I'd imagine that a wall of links on the main page wouldn't hurt, at least while the wiki is still in semi-stealth mode. A link dump is a reasonable starting point that we can use until we figure out how (if at all) we want to do the high-level organization. --Nate (talk) 19:04, 14 September 2013 (PDT)
goto in intro section?
I'm not opposed to mentioning
goto for completeness, but should it really be in the "intro" section? New programmers are never going to see it in use, and it seems a bad idea to introduce them to something so quirky, dangerous, and esoteric in an intro book. Not to mention that covering all of its quirks requires a lot more depth than would be available at that point (for example, the interaction of
catch blocks). --Indi (talk) 10:42, 16 September 2013 (PDT)
- I agree. By the way, there's no need to discuss every single bit. You can just go ahead and improve things. I think discussion is worthwhile only for wiki-wide policies, major changes and when there's disagreement. Otherwise a better idea is to invest time in the articles themselves. --P12 13:37, 16 September 2013 (PDT)
Proposal for another structure in the beginners-section
I really like the idea of having a good and free book for people who are going to learn C++, but while the current structure looks better than most of the currently available stuff, I still believe, that it starts to early with some of the low-level-stuff: For instance, I wouldn't teach pointers and build-in-arrays in the beginners-section.
Instead I propose the following structure for the beginners-section (everything not mentioned should instead be covered in the intermediate- or expert-sections):
Note that this uses some C++14-features. The rationale behind that is the fact, that C++11 will be past pretty soon and that there are workarounds for almost all uses that can be noted for people who have old compilers.
Some rationales for this approach:
- There are enough topics to pack them into some smaller subtopics which may help with recognizing structure while learning.
- The addition of string and vector to the introduction is the fact, that they enable you to write small programs that already do something. The fact that the basic idea behind strings and arrays is almost trivially to understand for almost everyone is another reason to do that.
- Moving the for-each-loop further to the front: This loop is another of these small features that makes many things easier and is easy to understand too.
- Since one should pass arguments to functions by cons-reference in later programs, references and const should be introduced directly after functions. References are again easy to understand and const is important enough to mention it here too
- Function- and Operator-overloading: I put them where they are mostly in order to keep related things together.
- IO may be moved bevore functions, I am not sure about that.
- I believe that basic templates are somewhat easier to understand than virtual functions and that new programmers should get used to them pretty early, because as the language currently evolves they will become even more important.
- Enums are relatively related to classes and unlike unions not that dangerous, so I put them there.
- I believe, that a proper introduction into the STL is very important to teach people into writing good code, so I would dedicate a chapter for that at this point.
- Since everything in the STL lives in the std-namespace, this might be a good moment, to teach the readers about what namespaces are.
- blank pointers and manual resource-managment are a dangerous topic and shouldn't therefore be touched in the beginners-section.
- Since std::optional will be a very elegant and fast way of returning failure and is somewhat easier to imagine than exceptions, I would introduce it before them.
- I like this proposal. It's a clear improvement over the current structure. I'm a bit unsure about std::optional, but since we can introduce it along simple error codes (or std::pair<bool,T>), being from C++14 land is not a problem. --P12 00:17, 19 September 2013 (PDT)
- Seems reasonable. Also note that good top-level organization might become more apparent as we fill in the individual items. --Nate (talk) 11:51, 19 September 2013 (PDT)
- Great! Since there seems to be consent about that, I'll change the main page. Then there are some points, I forgot when writing this:
- undefined behavior. While this is not a trivial topic, I do not see a passable way around introducing it early; early like in “really, really early”. UB is way too dangerous to allow people believing “yeah, It may be UB, but it will work in practice” (until they change the compiler-switches).
- A glossary with short definitions that would be nice, maybe in its own wiki-namespace. The descriptions of a topic should consist of a very short (one or two sentences) summary and a short (1-3 paragraphs) description. Possible example for undefined behaviour:
- Great! Since there seems to be consent about that, I'll change the main page. Then there are some points, I forgot when writing this:
- An introduction on how to set up your working environment on different platforms might be nice. It should however not be part of the core-book itself.
- A short introduction into what C++ is, what it's design-goals were and what implications this may have on programmers (somewhat around “C++ was designed with performance as important goal, so you need to ask for the seat-belts yourself”). This might be a good place to introduce UB too.
- Well, turns out it isn't that trivial to make it nice especially since the form I thought of would be incompatible to the names of the current chapters. So I just created a first version in my personal namespace. Feel free to change it until you believe, it might suit the mainpage. Some parts are clearly just mock-ups, but I believe that it may be a good base for further work. --FJW (talk) 17:12, 19 September 2013 (PDT)
- I'd suggest an additional chapter before "hello world", introducing some very basic but fundamental C++ concepts. Stuff that will come up again and again even in introductory chapters. Like "undefined behaviour" (explaining that C++ is underspecified for efficiency and implementation flexibility, which means when you break the rules, anything could happen - it could even appear to work fine - but in "C++ speak" it basically means "bad"), the "as if rule" (explaining that a compiler is free to not do exactly what you wrote, so long as what it does behaves as if it were what you wrote), the "one definition rule" (explaining that "stuff" (functions, classes, etc.) can only be defined once in the program).
- You don't need to go into any detail - just set things up so that we can say stuff like "undefined behaviour" in topics and it won't be meaningless jargon (and so that we don't need to qualify everything we say - like we don't need to explain that creating a variable doesn't necessarily equal a variable actually being created, so long as the program behaves as if a variable was created). I don't know what to call it or I'd put it in the skeleton myself. Also, shouldn't we give a brief explanation of "compiling", "linking", etc. - ie, the build process?--Indi (talk) 22:17, 3 November 2013 (PST)
Problems with locale-dependent stuff
While writing the parts about functions I encountered a few situations where I needed locale-dependent functions (toupper, isupper, islower). The problem is, that the automatic links point to the C-functions instead of the C++ templates which are used in the current versions. Is there a possibility to change this?
On a sidenode: I've been using the templates because I believe in “Don't show how to do things good by doing them bad” and therefore prefer the new stuff to the old. On the other hand this either requires introducing locales very early (together with std::string) or using it without much explanation. I am interested in opinions on that questions.
- I have been working on improving the linking for some time already. This problem should be solved at some time in the future.
- As for the second question, I think that we should keep things simple in the introduction section. Perhaps showing imperfect, but simple examples and adding a link to the advanced section would be better. However, I guess you can do as you wish for now: doing the fine-tuning in the future makes more sense. --P12 13:17, 6 October 2013 (PDT)
Style of the Chapters
We currently have several chapters that start by telling the reader that X exists, without explanation why X is needed and what it is good for. Personally I clearly prefer to start a chapter with the already known techniques and a realistic (or as realistic as is reasonably possible) example where they fail to solve the problem in a proper way. Starting from that, I introduce the new feature and show how it solves that problem.
I do this because I remember my own problems, when I learned C++ from web-tutorials, where I often couldn't understand, why a certain feature was of any use (why use const, when you can have a variable or a literal; why use classes, just pass all the paramters…) or didn't know what to use (mixing char* and std::string, blank arrays and std::vector…).
An example for a chapter that has all the technical stuff, but none of the explanations is Access Specifiers: It fails to explain why making stuff private can be a good idea, which is actually the most important part. I didn't touch it upto now, because I will probably include public and private in the chapter about classes directly and protected should most likely be taught once inheritance has been introduced, but there are currently other articles that have the same problem. Keep in mind that we don't write a reference for people who already know the language but for novices who may not have programed before at all.
- I agree completely. This will go into the guidelines page, when we have it. --P12 12:04, 18 October 2013 (PDT)
what has happened here
long time no update here, what has happened here?
if we need to restart this project, there are lots of things for us to do
or we should mark this project has deprecated for a long time on this page head