Talk:C++ Programming/Conventions/Archive 1

Common Programming Errors
It would be nice to point out some common programming errors, pitfalls and the like by highlighting it. Many books on programming have an inset with an icon indicating the type of the inset (general notes, common errors made in general & errors made mostly by people coming from some background (e.g. in our case a C or Java background may cause some confusion in people adopting C++), general pitfalls, pitfalls in some C++ implementations, etc.) beside it. We could also probably do something similar. There is already a common programming error in Programming:C plus plus Hello world. -- Paddu 12:46, 16 Dec 2003 (UTC)
 * What about Programming:Improving programming skills that will assume knowledge of programming and just focuses on improving style/skill so on? Dysprosia 07:01, 22 Feb 2004 (UTC)


 * Dysprosia, did you mean to respond to section 2? Section 1 deals with errors in programming, not styles. -- Paddu 08:01, 22 Feb 2004 (UTC)


 * This could be done with something similar to infoboxes in Wikipedia -- Paddu 20:45, 17 Oct 2004 (UTC)

Brace Style
An important problem is how to have NPOV in the indent styles of examples. -- Paddu


 * Present all the styles and "let the reader decide"... at least that is my idea. -- Emperorbma 19:59, 16 Dec 2003 (UTC)


 * I didn't quite get that. Obviously each example cannot be presented in all styles. So we should present one particular example in all styles & the rest all in the same style as a `convention we'll adopt in this book' (which may itself be controversial). But then the example must be comprehensive enough (to include, e.g. cuddling of else, do-while, etc.). Then what about the examples which are presented before this comprehensive example? -- Paddu 07:37, 17 Dec 2003 (UTC)

Separate Chapters
y not split the content into different chapters? --Yacht (talk)Q 02:48, 21 Feb 2004 (UTC)


 * Follow the link to "your first program". I have been making separate chapters. I am just reluctant to make N different pages now itself (them each would be with nothing more than a few lines). Once each chapter is sort of complete, content from here would be moved there and a link added here. -- Paddu 06:47, 22 Feb 2004 (UTC)

Broad overview ?
Sorry to ask, but do you think you have here a broad overview of C++, like the first chapter in Kernighan & Ritchie ?

Now the same subjects would have to be expanded in specialized chapters, right ?

Hgfernan 12 May 2004

What must be covered
IMHO there should be a book covering C++ without reference to platform & non-ANSI libraries, so that people who want to use various C++ libraries can first get to learn C++ per se. And, IMHO this is that book. Of course, there could/should be books about the various C++ libraries, e.g. MFC, boost, GTK--, etc. But they should be covered in books different from the book meant for learning C++. Any comments on this? -- Paddu 07:12, 20 Sep 2004 (UTC)


 * I do agree that things must have a structure and a logical one if possible, using as many references to any C++ oriented content information would be only contributing to the goal (readers <= contributors), if there is any part that would could be made into a separate work they should be moved, I've done that with OOP part (as a test, but it pretty empty, if someone dislikes it they can change it), more important would be saving any work already done under the same license like *How To Think Like A Computer Scientist Learning with C++ by Allen B. Downey and other free work under a compatible license before they are lost and mailing other free content authors so the information remains free for all...


 * OOP is central to C++ and would have to be dealt with in a book on C++, but a book on C++ should not deal with MFC, etc. as they are not required to learn C++. There could/should be (a) separate book(s) on OOP; they'd probably deal with not only C++ but other OO languages as well. IMHO C++ is one subject for a book, MFC is another, general OO is yet another. Each would ideally be dealt with a separate wikibook.


 * Agree... but other libraries should be referred to... I personably don’t have a problem with some examples on the differences of approaches etc... but yes I agree that C++ and STL should be the main subject... -- Panic


 * Trying to pour in material from 3 subjects into one book would IMHO not lure contributors but would turn them away, since they'd think it's an unorganised set of notes rather than a textbook. -- Paddu 20:45, 17 Oct 2004 (UTC)


 * Disagree... as we are working on virtual space and not restricted to paper or other media a dif. page or chapter for MFC (until enough data to form a dif. work) is more logical than a different empty book for it... people would participate more if given a vast range of options to build upon, this is one of the reasons that a single "huge" page would work better, given the restrictions of wiki. (more on that below) -- Panic

My replies removed
My replies to many of the above threads have been wrongfully removed. -- Paddu 13:57, 18 Nov 2004 (UTC)


 * These include threads that User:Panic2k4 calls dead, and includes threads about User:Panic2k4's behaviour in Talk:Programming:C plus plus. My replies can still be found in Talk:Programming:C plus plus and Talk:Programming:C plus plus/single page. Some stuff I wrote to him are also at User talk:Panic2k4. -- Paddu 14:09, 18 Nov 2004 (UTC)

Rearranged discussion "area"
The above three sections enclosed within horizontal rules is User:Panic2k4's interpretation of the previous discussion. I'm opposed to his/her refactoring at least because:
 * 1) I was misquoted at least once &mdash; Panic's interpretation is that I asked someone to be nice, though I'd just said that doing something would be nice.


 * Geezz Paddu just correct them, people do make errors, English is not my natural language, and try to not spend my time taking things that seriously... (probably the mess this was, if anyone changes your lines you wouldn't notice it :)


 * 1) The interpretation makes at least one false claim &mdash; It's false that I didn't implement the highlighting I proposed. All the pages that I edited (except those in which I added navigation links) follow the convention I proposed.


 * Didn't see any and I didn't contribute to any modules only to "the book" (modules have seperate discussion "boxes" (hint) ) was this miss plassed here ?


 * 1) It calls proposals without any opposition as dead.

I didn't check for more errors as I don't have much time. Besides, even then I wouldn't be correcting them as IMHO they form a comment Panic has posted and I believe I shouldn't edit his/her comment. Presenting the original is an easy way to make clear what each person said.


 * Humm the originals are still there only commented out so to reduce the mess (I reverted it again), and missquoted are is not the same as edited, it's easier to prioritize stuff as I have arranged it, please try to give it a chance, as for the dead proposals as adopted, heck if a house is pink I say it's pink I dind't select the color...


 * Please state what proposals you wish still to debate (if you still consider that for example the highlights are open, you should consider helping on heerr highlighting stuff :) lol at this point in time I don't think it's a great idea if that would have been settled before no time would be have to be lost on this (humm btw for example "In My First C++ ..." I didn't seem to notice any nor in the other modules I've seen...)
 * It can be done when all sections are filled and a full revision starts, but now it's a bit late on the game

And BTW Panic, Dysprosia is a "she" not a "he". -- Paddu 13:11, 8 Nov 2004 (UTC)


 * Lol I'll correct that one :)--Panic 02:10, 9 Nov 2004 (UTC)

moved from my talk page as this is relevant to this topic... (there = here)

Stop "vandalising" Talk:Programming:C plus plus with your own ideas

What you said there: "If you are an active contributor / engaged on any of the proposals you are free to edit this section" is not the wiki way. Everyone is free to edit any section. Stop adding this kind of nonsense. Thanks! -- Paddu 05:16, 9 Nov 2004 (UTC)

I don't think I'm vandalising anything My First Contribution-as it is now... (you can always ask for moderation if you have your mind set into it). I'm just asking for your opinion on some proposals (and some were already "adopted" by contributors or just ignored) and take your point or of any other "major" contributor into account, the ideia is to make contributors in general happy... geezz

As for the warped ideia you have on the humm wiki way... wiki pages may have passwords and other "protections", I didn't and can't prevent any non humm "major" contributor from editing the section, it's just a request and I do think it's a logical one so to keep some order on it... geeezz you are to litral for me, first you wrongly accused me of vandalizing and them make me spend this time debating a self evident point don't be so single minded (almost anal) on the subjects, take the time to think on what/how you did/react and how I could have gone about it, I think I've been contributing so don't call me a vandal ... txs

PS: I'm a "he" :) --Panic 01:39, 10 Nov 2004 (UTC)

Having all material in a book in a single page
Can't the reference tables be moved to the main page into the related part of the doc and use anchors to refer to them ?

This does have something to have with previous discussions about removing part of the work to other pages but as this is not an independent topic (it relates to misc. parts of the main topic) -- Panic


 * It's infeasible to have an entire book in a single wiki page. It may be OK for some people to read that (there do exist a lot of e-books available in "one-big HTML" format), but editing such a page would be difficult. Yeah, we have section editing and all that, but still it is a pain. After submiting it, you've to wait for the whole book to load again. Which reminds me... What about people trying to learn about just one language feature. Do you want them to wait for the entire book to load? That's why pages in the context of wikibooks are called "modules", not "books". Depending on the size of the book, each "module" may be a separate chapter or section or sub-section or anything.


 * If you want all chapters in one big HTML, it should be possible to create a page like this:


 * but the navigational links I've added to some of the chapters won't point within the page but to the page for individual chapters. But that should be the least of our problems. The real problem is that the servers would slow down. -- Paddu 20:17, 18 Oct 2004 (UTC)


 * A single page from my point of view is the best trade off, for the user and the writer, as stated above any contributor would find more easily were he can be most useful and avoid repeating already contributed information, as a reader I do really hate wiki because of the limitations it gives to export to a non wiki env. like to get a copy of the work as a PDF. -- Panic


 * What was dicussed before was not trying to include all C++-related topics into this book but to deal with only one topic &mdash; C++. The other topics must be in different books. Of course there should be a link to those books here and a link to this one in those, but each chapter in those other books should not be mentioned in the table of contents of this book. -- Paddu


 * Agree, but the "topics" can be easily moved later if found to be extensible enough to be a stand alone book, moving empty topics will only fragment the user/contributor base... -- Panic

and there isn't a wiki "extractor" (does it?) that would facilitate getting a copy of all the work I do think that it should be avoided and only use external pages to start independent "books" (works with private topics), I have also tried to find an offline editor (that isn't a Emacs or Unix solution...), does anyone know about one ? -- Panic


 * Probably you are looking for Special:Export?


 * Nope, something like a OpenOffice plugin something on those lines... I dont want to install a server and wiki on my comp to be able to edit offline :)... -- Panic

... and still on forking the work into multiple books. First lets have a working "book" and then we'll trim it out, using s streamline structure without references to multiple subpages will help to desegregate other topics, hec... even STL, that is part of the standard should have a separated book only for it, but lets try to just keep it on topic and with a simple and logic structure, then we can see if it is worth to fork it for the moment all content (on topic) will help to bring contributions ... -- Panic


 * It's difficult to have a working "book" without structure, with just random stuff about every C++-related topic thrown about. Talking of forks, splitting a program into a lot many source files is not equivalent to creating forks. Forks in wikibooks would be having two different wikibooks on the same subject. Is there any other book on C++ here? -- Paddu 20:45, 17 Oct 2004 (UTC)


 * Ok, I should have used thread of subject and not fork (topic would also be wrong as a topic can be linked to a external subject), but I've seen your changes to the "Guide to Writers" but is there a way to list all "modules" on a single page so anyone can get a easy copy of the book (for printing or just to avoid repeating info or just to link to the relevant areas ? ) if not dividing the work into multiple modules is not a good idea it will only hide information and segment the readers reducing the writers as they will only see blocks of the work and probably if a users comes to the book as a reader the probability that he will contribute to a section he wants to read about is less that to a part he already knows, in modules only people that already have some degree of knowledge on the subject would contribute and I really doubt that this would result on more work being done, to do spell checking I don't need to know C++ (for example)... -- Panic


 * The intent is to make the readers aware that they can edit any page, not just what they are reading. With Wikipedia, the average newcomer is tempted to read more & more pages following various internal links, and hence can easily arrive at something known and start contributing to that article. In wikibooks, the no. of links is low and this may be a problem. But IMHO the reader can easily guess that there is more than one module to a book and search for other modules in a book.


 * As far as coverage of new subjects is concerned, the idea probably was to list the books expected to be written in a bookshelf, and a visitor to the bookshelf can easily find what subjects he could contribute to. This approach would not work if bookshelves are (e.g.) given lower Google ranking than to a particular book. In such a case most visitors would only visit that book and might not be able to guess that they are free to contribute to any of the other books listed in the bookshelf.


 * I can't think of a solution to the problem other than what I've mentioned, namely have a huge page that instantiates each page of the wikibook as a template (did you know you could insert the contents of any page into any other page using templates?). It is possible to also have an edit link to individual pages, so any reader could be lured into adding content for any of the modules. But the real problem is that having large pages both irritates the reader and stresses the servers. I think we could get a better solution if we ask this in the Staff lounge, which has a greater visibility.


 * BTW, please sign your comments with a  ~ . It's difficult to find which comments are by whom. I'm having a tough time taking our discussion to the Staff lounge. -- Paddu 14:42, 20 Oct 2004 (UTC)


 * Done -- Panic


 * As it turned out, all the anonymous comments were by the same person, and I didn't have time to take this discussion to the lounge. Will do so today. BTW our conversation is quite large and I've decided to give a brief description and link to this page instead of copying the entire conversation there. -- Paddu 07:23, 21 Oct 2004 (UTC)


 * How about an infobox in each module of a book, which includes some text like:


 * -- Paddu


 * That is a great idea, but not to empty books (that is really very frustrating), btw keep those wiki wiki codes coming it's helping my learning curve :) -- Panic


 * That way you may not learn much. Read the help pages here and in meta to learn more. I believe you can get a better idea about Mediawiki and the way we work in Wikimedia projects by perusing the pages in Wikipedia in the Wikipedia: namespace. Not all those pages have been ported to Wikibooks.


 * Since you seem to have arrived at Wikibooks without first having been to the 'pedia (please confirm this), you might be able to give a better insight into how wikibooks must be different from wikipedia. IMHO red links are not frustrating, but rather an invitation to contribute. A wikibooks reader oblivious of wikipedia might think differently. BTW you could change the way broken links show up by changing your Preferences. -- Paddu 07:23, 21 Oct 2004 (UTC)


 * Er... That's not an infobox, that's more of a navigational template. -- Paddu 07:23, 21 Oct 2004 (UTC)

Here's my 2c. A book has a lot of largish chapters - let's emulate this. Having everything on one page disadvantages the reader in having things referenced, it's easy to bookmark a module page to a certain section, but it's not if everything's on one page, since one has to look through that to find something. Not to mention it's more difficult on dialup connections. It also allows one to structure the material and have different people working on different things without loss of apparent continuity in the text. Speaking of forks, I am strongly against this. If we have any chance of making something decent here we need to pool our resources and create something unified. Dysprosia 21:32, 2 Nov 2004 (UTC)

Here is a possible solution: Either way, the text needs to be split up into different sections. How about splitting up this page into chapters and having more lecture style material more suited for a Wikiversity type course which can be a bit more freeform as Panic seems to be more comfortable with? (Though you will need to break it up into a set of lectures regardless, and most importantly keep it structured).

HTH Dysprosia 10:30, 9 Nov 2004 (UTC)

Lol, sorry about the "he" Dysprosia you are part of a minority so I did take it for granted, I've been corrected and switched any wrong gender references :) (Hope it alright now...)

I'll elaborate it more here and them move relevant parts to the "proposals section", I understand that you are referring to modules (separated pages) as chapters and sections... as for the order or structure I do think it's taking shape but stuff needs from time to time to be moved around just to make sense (we can't talk about classes before going into what OOP brings to C++ etc...), as for the fixed idea Paddu has with modules, I'm not against it nor mind set into a huge page but to make it a logical work. If we have multiple pages and with it discussion pages etc... it makes it a very difficult job on making a good work just take a look on the wiki bib. (on the previous modules) they go all over the place, I think that the problem is that people tend to look at this wiki book as an extension of wikipedia and this is separated work that must stand by itself if we fragment it it stops being a book. I'm taking the road set by P3 "move chapters to modules as they were finished" (they aren't) and see if the solution Paddu indicated will work (transclusion, I think its a great option), still waiting for him to give me a working example but that would solve the problem of extracting all content to let's say a .TXT file and make it easier to coordinate edits (stop the duplication) and keep the ease of editing (if you go into the history you can easily see that people edit and contribute to different "chapters" that would be made impossible if using modules at this stage... ufff I think it's all, combined with I and others have said before, will this close the subject ?!? (until we have a complete "chapter") --Panic 02:05, 10 Nov 2004 (UTC)

Where is the reference to the STL ?
The book doesn't have any reference tothe STL. Since it is a part of the C++ standards, is there a plan to create a section on it? --Mecanismo 13:31, 21 August 2005 (UTC)

Altering how talk pages are structured
As there seems to be no discussion about the cover image any more and seems to have been finished, I think its discussion should be removed. If for some reason someone disagrees with this I suggest, merging it with an archieve of previous proposals. I also think the link to book editing should be removed as well replaced with a link to help for editors and/or help for wikibook users. I also think the parts on merging contents and orphaned pages can be elemented since any merging and orphans should of been taken care of by now and the end of the main page lists anything that people think should be merged or added and the discussion on book contents seems to be the place to discussion it. I think copying and/or moving conventions and future contents that have been discussed and agreed to should be placed on the main talk page for quick access with a notice to not remove whats listed here, but to debate them if people disagree in the aproperate discussion.

Something like this to replace the main talk page:

== See Also ==
 * Before contributing to this book, read Wikibook Policies and Guidelines.
 * For information on editting wikis see help for editors and help for wikibook users.
 * See Archives for older talk pages.

Please try to limit discussions to the related discussion page:
 * See Conventions for debates over conventions used in this book.
 * See Contents for discussion and planning of books contents.
 * See the talk/discussion page of the related module for discussions and debates limited to that module.

==Conventions used in this book== ==Book Focus and Direction==

with maybe the see also part placed on its own page so that it can be included on any talk page for this wikibook to elemenate duplication. --darklama 18:42, 30 September 2006 (UTC)

Please move this to the proper section... And I disagree.--Panic 04:48, 1 October 2006 (UTC)

Is there anything you disagree with specifically? The choice of what cover image to use seems like a proposal that was finished. The help for editors seems like it would answer any questions related to editting making the book edit part unnessary. it also looks like its dead and could potially be duplicate contents. --darklama 17:21, 1 October 2006 (UTC)


 * Before contributing to this book, read Wikibook Policies and Guidelines.

This is already on the book itself and sending it in that "In your face" form, could just scare contributors.

Probably including the link in every existing talk page to the policies and guidelines would be helpful l is there a template we can implement on contributors discussion areas in genera (small fonts) and not in a red background would be great. (or on the side of the page, as V2 of the book something on those lines...) --Panic 03:41, 12 October 2006 (UTC)

Your right, it is be a bit "in your face". If you have better wording suggestion, go for it. The idea is to cut down on needing to point out specific guidelines or policies that are better understood by reading them. For example "avoid copyright paranoia" is better understood by reading the policies and guidelines. Then again it may not be necessary at all since the "help for wikibook users" includes a link already to policy and guidelines. I don't see a red background, its all white here, must be something on your end. I don't know if a template for it exists or not yet. The closes I know of off hand is which gives:

Come introduce yourself at the new users page. If you have any questions, you can ask there or contact me personally. --darklama 05:58, 12 October 2006 (UTC)

Again you misunderstood me, what I said was, we could probably use a banner (or something like V2 toc) and place those links and other info in all talk pages but not with a red background or big fonts. --Panic 16:14, 12 October 2006 (UTC)

I don't think I misunderstood you this time. I was answering your question. There doesn't seem to be any existing template, except maybe, we would need to create one to use on all talk pages. It doesn't have to be a red background or big fonts, I was pointing out that what I used above doesn't use a red background, but a white background, in case thats what you see on your end. --darklama 19:08, 12 October 2006 (UTC)

Altering the TODO box logic
I Propose altering the way the TODO boxes are used at the moment, the idea would be adding a TODO template on the C++ Programming namespace with a redirect to the existing root: template, this would provide a easy what on checking where TODO boxes are on the book and add the what links here link to the Content discussion. --Panic 05:36, 30 October 2006 (UTC)

The TODO template could probably be changed to categorize pages in something like Bookname/Todo, but why is it needed? --darklama 03:14, 31 October 2006 (UTC)

A new template (reworked that is) will not be needed a simple redirect from a local (in the book namespace) to the general one would provide a whatlinksHere list of were all the TODO boxes are, so to facilitate contributions and prevent that people that add them forget or get confused by moves or text changes...--Panic 05:09, 31 October 2006 (UTC)

Sounds to me like the category would be the better option, because the TODO template may be used by more then one book and people may forget to create a redirect. The category would ensure its always available for any book that has things to do that makes use of the TODO template. --darklama 12:01, 31 October 2006 (UTC)

Try it then lets seem how it feels, I do think that the TODO box in itself doesn't need a link to the category, that could be done in per book bases in the talk section.--Panic 15:37, 31 October 2006 (UTC) PS: This discussion should be moved to the template page, so if anyone objects sees what our intentions are.

Making the template not appear in the category isn't a problem, thats easly done. --darklama 16:14, 31 October 2006 (UTC)

Humm ok but I don't see another way of doing what I said having a Special:Whatlinkshere/Template:TODO with only the C++ Programming Pages.--Panic 17:39, 31 October 2006 (UTC)

Yup I remember now why we didn't use the category on the TODO box, the box is intended to help editors/contributors not to crowd the navigational aids, even if in part it would help the page listing isn't specific to a book.--Panic 20:23, 1 November 2006 (UTC) PS: I will be moving this discussion to the TODO box talk in a few days (3 max)

So are you saying now you don't want it?! I had went ahead an added a category for it already, since pages (including templates) should be categorized. Maybe it can be somewhat helpful anyways. See Category:TODO. --darklama 23:09, 1 November 2006 (UTC)

-

I'm saying that I don't like it, there is no need to have an extra link in each page (on set of pages) that use the TODO, a quick way to see what book pages used it would suffice, as it is it only makes like a bit more confused to users, but I can live with it.--Panic 17:11, 20 November 2006 (UTC)

Tables, Figures and More
'''From prev. debates...''' I like the green boxes, and i would re-use them until someone can come up with a better solution.

Here is an example:

I would suggest:
 * TODO for TODO notes (since that's already there)
 * Programming:C_plus_plus/Pitfall for common errors
 * Programming:C_plus_plus/Portability for portability tips
 * Programming:C_plus_plus/Practice for good practice

with right now the only difference being what is written there.

--Max 01:26, 18 September 2005 (UTC)

Have a box template that can be used for tables, figures, examples and other commonly tools used in technical books. For now use a fix style. In the future if we can get it approved, allow for customize style by way of class or id name thats available in all monobook themes.

Usage would be one of:

which would be rendered as:

I also agree that we need to use several different types of notes with different styles to distinguish level of importance of the information being given. --darklama 20:34, 11 October 2006 (UTC)