Talk:C++ Programming/Conventions

Approved Conventions /Talk pages

Proposed Conventions
This page describes proposed conventions that should be followed in editing this book. As a general rule, all guidelines from Manual_of_Style are in effect. These conventions are not adopted / contested / resolved yet. Add and explain your proposals here and a warning on the main talk page of the book. Please remember to sign and date proposals.

Contributors come from many different countries and cultures, and have widely different views. By treating others with respect, we are able to cooperate effectively in building an instructional resource. Check Etiquette for pointers.

Please do try to check responses to your post from time to time, if you think some action should be incorporated into the proposals and a given time of inactivity (7+ days is ok) is verified, move the relevant information to the proper location, or take any just action as justified by your post and archive the original thread...

Proposals (now inactive for more than 7 days) should be moved to the Archive2 after some references are added to the proper proposal location.

humor
Humor should be encouraged in this book, because humor helps people learn. Therefore, AlmostNeverDeleteHumor.

This allows this book to fill an empty niche: there is apparently no other humorous introduction to C++ ("Does there exist a humorous C++ tutorial?"), even though such things exist for other languages.

--DavidCary (talk) 18:10, 19 June 2010 (UTC)


 * I would support a AlmostNeverDeleteHumor convention but not a convention that encourages humor. Even if similar the goals are different. --Panic (talk) 01:03, 20 June 2010 (UTC)


 * I personally think it is a fine idea to encourage some amount of humor amounts of humor. Some exceptions for off topic and inappropriate humor should be made though, those can be deleted. Thenub314 (talk) 07:29, 20 June 2010 (UTC)
 * The question here is the need to make humor a goal, I don't see it as a necessity and it somehow diverges from the scope of the book, that is not to be a humorous work. In any case I don't think there needs to be a convention about this at the moment, I will try to spice it a bit and respect the spirit of AlmostNeverDeleteHumor as I work on the book.  --Panic (talk) 10:36, 20 June 2010 (UTC)


 * I disagree, I think it is perfect for a convention. As noted above it will improve the educational aspects of the book, and it is something editors may not realize is welcome, making it a prime candidate for a convention.  It is more of an issue of writing style then subject matter, so I don't really think that it diverges from the scope.  And as we all know, the name of the C++ language is itself a joke, but it really should have been named ++C. Thenub314 (talk) 14:59, 20 June 2010 (UTC)


 * diverges from the scope of the book? I think you misunderstand my proposal. Let me put it to you in the form of two syllogisms.
 * "People learning" is the goal of the C++ Programmming book.
 * Humor helps people learn.
 * Therefore, humor helps fulfill the goal of the C++ Programming book.


 * The Conventions page should encourage non-obvious things that help fulfill the goal of the C++ Programming book.
 * Humor helps fulfill the goal of the C++ Programming book.
 * It is not obvious that humor helps fulfill the goal of the C++ Programming book.
 * Therefore, the Conventions page should encourage humor.
 * --DavidCary (talk) 15:18, 27 July 2010 (UTC)


 * At this point of development of the book the convention should not encourage any change to the level of humor of the text. I'm not against adding funny quotes or mentioning funny situations or comical examples but at this stage of development creating grounds for inconsistency in the writing style shouldn't be encouraged nor does it need be specifically protected by a convention (as it wasn't one of the goals set for the project). To my knowledge no funny content has been killed on the production of this book.
 * The concept is interesting, but with the level of participation in the book you can by action and by direct contact with the editors have better results that by the addition of a unenforceable and open ended call for humorous content, not all type of humor is proper, translatable across cultures and able to mix well with the scope of the book. The concept is interesting but as a proposal it wouldn't have any value, especially due to how the book has been written. --Panic (talk) 16:23, 27 July 2010 (UTC)

flat page structure
For years, the C++ Programming/Conventions page has said
 * "We are using the slash convention with a flat page structure as described in Naming_policy".

Recently it has come to my attention that the Wikibooks naming policy no longer defines "flat page structure", and so it is unclear what exactly that means. We can't expect new editors to dig through the history of that policy to learn the definition of that term.


 * flat page structure means that every "module" of the book after the title page has exactly one slash, of the form "Book_Title/CHAPTER".
 * For example, "C++ Programming/Operators".
 * deep hierarchical structure means that the the book is divided into chapters, which are introduced with a "module" of the form "Book_Title/Chapter_Name", and each chapter is further divided into pages of the form "Book_Title/Chapter_Name/Page_Name". Perhaps there is a larger grouping of chapters into a larger section, and further sub-divisions of the hierarchy, leading to any number of slashes.
 * For example, "C++ Programming/Programming Languages/C++/Code/Statements/Variables/Operators".

As best as I can recall, the above definition is equivalent to the definition of "flat page structure" that was once part of the naming policy, and is also equivalent to the definitions currently on Help:Editing and the Horticulture/Manual of Style and Using Wikibooks/How To Structure A Wikibook. (Those pages also list some advantages and disadvantages of the "flat page structure" vs "deep hierarchical structure"). --DavidCary (talk) 17:24, 27 July 2010 (UTC)


 * For years that convention was never fallowed, nor did I interpret it as "flat structure" or "flat hierarchy". In any case I did yesterday spend time digging around on the subject and the only discussions I saw was on the Naming policy talk page (referring to that flat structure), if you are interested the first vote for the "/" convention was in 2005, I voted against and the vote didn't pass it was later approved in 1 March 2006, I didn't see on the approved text mention of flat whatever.
 * Horticulture has now mixed structure, that book substituted the chess book that substituted the Ada Programming book (the original poster child for the flat structure). In fact today is extremely difficult to find any book of considerable size that still uses that structure and no new books are using it intentionally (all books start in a flat structure). I've confirmed that the C++ Programming never used or enforced the convention, or used that structure, beyond the initial days that I used a monolithic approach to the text. In fact the convention was never proposed or discussed (I have added the relevant link to it on the "never"), in violation to the decision policy.
 * In any case what is the point of the above post ? It doesn't seem to be a proposal.  --Panic (talk) 18:30, 27 July 2010 (UTC)


 * Silly me, I left out the actual proposal.
 * I propose adding a link to that convention that links directly to the definition of "flat structure" (and describes its advantage over the alternative), changing it to
 * "We are using the slash convention with a flat page structure as described in Naming_policy and Using Wikibooks/How To Structure A Wikibook."
 * --DavidCary (talk) 19:06, 27 July 2010 (UTC)


 * I take by the first post that you aren't happy that the Naming_policy never defined "flat structure" (this isn't the forum to change that). I also take that there are different concepts around what "flat" something is, even Using Wikibooks/How To Structure A Wikibook seems to be badly written as books can have a flat structure without including chapters in the navigational scheme created by the "/" convention (that was my understanding of "flat pages" on our convention, that section can be greatly improved and cover all possibilities) in any case it seems that the C++ Programming never had a "flat structure" and has in fact being moving to a highly structured hierarchical one, this practice seems to be the one chosen by most of the larger book. If the proposal is to revert the book to a flat structure, I'm not only opposed to it but sees it as removing the ability to fully enjoy the navigational aid provided by the "/" convention, in fact such flat structures create a need for external and hard to maintain navigational aids, hinder interconnection of the content, something that in the C++ language is extremely (even regrettably) necessary (for instance the keyword has 4 distinct implications, without a deeply hierarchical structure it would be impossible not to duplicate content across several sections of the book (take a look at the static page content to see how we managed it).
 * In any case since the convention no longer mentions "flat" the need to the link no longer exists. --Panic (talk) 08:06, 28 July 2010 (UTC)


 * Are you proposing to change the convention from "flat structure" to something else? What structure would you prefer? Would you prefer a "Book_Title/Chapter_Name" plus "Book_Title/Chapter_Name/Page_Name" structure? Would you prefer a "Book_Title/Section_Name" plus "Book_Title/Section_Name/Chapter_Name" plus "Book_Title/Section_Name/Chapter_Name/Page_Name" structure? From 2009 back to 2006 and probably earlier, the Wikibooks naming policy had a definition of "flat structure". That definition was moved to the page that I mentioned before. Is there a page somewhere that defines the structure "chosen by most of the larger book" and its advantages?
 * What structure are we aiming towards? I'd like to at first understand what it is. After that, I would like to learn its advantages.
 * If some editor wants to add a page to this book, to what name should we move it? As far as I can tell, the C++ Programming book currently has an inconsistent structure. Therefore, it is not currently possible for me to make new page names that are consistent with the current page names.
 * For example, let's say someone writes a page about bitor. Should we move it to
 * C++ Programming/bitor
 * C++ Programming/kw/bitor
 * C++ Programming/Operators/bitor
 * C++ Programming/Programming Languages/C++/bitor
 * C++ Programming/Operators/Operator_Overloading/bitor
 * C++ Programming/Programming Languages/C++/Code/bitor
 * C++ Programming/Programming Languages/C++/Code/Keywords/bitor
 * C++ Programming/Programming Languages/C++/Code/Statements/Variables/Operators/bitor
 * or perhaps somewhere else?
 * --DavidCary (talk) 05:50, 30 July 2010 (UTC)


 * There isn't a convention for "flat structure" anymore.
 * We never used it, in the terms the majority seems to interpreter it now. In particular I don't like the idea of including the chapters in the path (hierarchy). Recently I did some changes that puts some pages in that type of hierarchy but it is only for structural consistency and navigability.
 * Examples: C++ Programming -> C++ Programming/Chapters -> C++ Programming/Chapters/C++ -> C++ Programming/Chapters/C++/Summary or C++ Programming/Chapters/C++/Print Version  (and made use of  1, 2, 3, 4, 5 for the chapters pages)
 * It seems to me that given the actual arrangement it would be C++ Programming/Programming Languages/C++/Code/Keywords/bitor (since even if MS defines them as macros) they are indeed keywords (this is covered in Logical Operators) and would be used in the rest of the book with the template.
 * My experience dictates that most editors will never have problems with the page structure, since most will add to the already existing pages and forgo getting into that type of issues, and if confused will just ask or create it on the root, as indeed the book has now requirements of structure and order/organization/low that requires specific considerations when adding significative content. To make large structural changes would require one to have a good understanding of the already existing content and structure and most editors will not have the time or inclination to learn about it.
 * I've been also thinking on the concept of a "humorous" book on C++, the viability not of altering this one but on creating a derivation that indeed has humor as a goal. I'm game for the creation of a derivation of the C++ Programming book with that goal, if it will follow the same content structure and will only reuse the content already present of this book, that is primary contributions will have to benefit the C++ Programming first.
 * It will not consist of a duplication of content (as it will have a distinct voice and focus on humor) nor a duplication of effort since the priority will be to extend the source material first. I propose the title of "A cynics view on CPP" (being the PP intentional as to provide fodder for jokes). --Panic (talk) 12:03, 30 July 2010 (UTC)
 * I also call your attention to Hierarchy naming scheme‎ Request for Deletion (since it relates to the historic relevance of the hierarchical structure of Wikibooks) you may wish to participate on the discussion. --Panic (talk) 13:29, 30 July 2010 (UTC)


 * Dear C++ Wikibook editors,
 * This book currently has modules with names like "C++ Programming/Programming Languages/C++/Code/Statements/Variables/Operators".
 * Let me call it the "6 slash structure" for now, to distinguish it from the "Book_Title/Chapter_Name/Page_Name" structure. Is there a better name for the 6 slash structure?
 * Is there any description of the 6 slash structure anywhere online?
 * (I honestly don't know any good reason for redundantly mentioning "C++" twice in the name, but I assume Panic has at least one good reason for doing that).
 * Panic seems like a pretty smart guy, so I'm assuming the 6 slash structure has some slight advantage over the "Book_Title/Chapter_Name/Page_Name" structure for the C++ Wikibook.
 * Therefore, I propose updating this convention page to mention the structure this book is *actually* using -- something like
 * "We are using the slash convention as described in Naming_policy, with a 6 slash structure as described in ... ."
 * --DavidCary (talk) 18:45, 9 August 2010 (UTC)


 * The rational not the use Chapter_Name in the "path" is that it would prevent to easily move pages from chapter to chapter or restructuring chapters (for instance we have a clear unbalanced chapter structure at the moment). I foresee a need to at a later date reshape them, it all depends on the level of content and how it is expanded.
 * A similar issue is created by fixing the number of the depth of the path, we can easily use more.
 * I think that the issue or problem you see is that you are putting too much value on the pages names and location these are highly volatile and don't need to really express the content, take for instance the page that is causing you confusion the C++ Programming/Programming Languages/C++. It is a given that all pages should start by Book_Title, that is unavoidable and doesn't need to be stated. Pages not named so would fall outside of the project namespace (but exceptions can be created as for example in the issue about tables you have risen not so long ago). I don't see an issue on putting them on a special namespace or using the Template namespace if no one objects. In this particular case the path order is not in accordance to the book structure, this is the first page of content of the book but the order reflects the use of the slash convention as a necessary aid to navigation (we in the past have tested navigational Templates, but found that they are extremely hard to maintain and create unnecessary attrition regarding esthetics and technical accessibility.
 * The conventions do not necessary need to reflect every detail, they should only be used to prevent conflict and ease participation, if extremely detailed and complex they can even become a barrier to participation. Beyond this discussion there never was any issue about the structure (path order, there were several request against the previously monolithic structure, and on the order the content was presented). I wouldn't see an issue if someone just ignored the path structure and created pages on the root of the book. I do value more the content someone can provide to the ability and time they can spare to understand our structure or even fallow our conventions, the content can always be moved and made to conform to the general practice.  --Panic (talk) 19:19, 9 August 2010 (UTC)