kaylalewis
commented
10 years ago I just went through this chapter too, and I commend you for your thorough explanations of C++. I can't even imagine how much time was spent on this. I have some feedback concerning the nature of the chapter itself:
Maybe instead of a “how to read the book” disclaimer in the C++ chapter, we should add it before the chapters even begin.
The lead up to this chapter is a good story, and I think backgrounds on all of the writers and how/when coding became interesting to them could be a great component to this book. I think it should be included elsewhere. If one author does it, then they all should.
The structure of this chapter is questionable. Talking about functions, and then suddenly delving into a history of programming languages threw me off. History is best served at the beginning. It gives C++ more of a personality and a tangible backdrop.
That being said, the level of explanation that C++ can reach in one chapter of a book is problematic. I think a consensus needs to be reached for just who will be reading this book and how much outside reference they’ll need concerning C++. It isn’t something that can be successfully covered for a newcomer in one chapter. If this book is about openFrameworks, starting with a long, dense C++ chapter seems like it might deter a lot of people.
Maybe this chapter should be C++ basics in relation to oF. For example, how does a function’s syntax look in oF specifically? I’d refer people to some books on C++ alone in the beginning of the book, and then structure any C++ explanation around and within openFrameworks, because this is a book about openFrameworks, right?
Breaking this chapter down into three or four separate ones seems fitting. If someone knows nothing about C++ when starting this book, this is 100% the most complex learning experience in the entire book. Having functions, loops, variables, etc. all sandwiched into one chapter doesn’t work if the goal of this book to cover C++ and hold everything a new programmer needs to know in its pages. So who is the target audience?
Pop culture references made it more engaging and relatable. I could tell you were having fun writing with them, and that made me want to keep reading. Getting people to relate to dense subject matter is a skill, and readers can tell when an author is bored. I never felt like you were bored. Impressive.
I hope this feedback is helpful. This chapter is tricky and definitely stands out next to the rest subject-wise.
ofZach
jtnimoy
mikewesthad
tpltnt
@jtnimoy I just got a chance to give your draft a close read. It's definitely great so far - easy to read and entertaining (Back to the Future reference is my favorite).
Your figures that explore the code visually (e.g. figs 11, 18, 21, etc.) will be a huge boon for those readers who are coding for the first time. Figs 28 + 29 are simple examples that are particularly effective. They help elucidate what is going memory-wise with just a few extra marks+words, and that's great for helping beginners see "beyond" the code to what is happening underneath.
I like ideone though I did run into a bug (that I couldn't replicate). Changes to the code wouldn't get compiled into the version that was being run. Tried saving, running multiple times, making multiple edits. I ended up chalking it up to having the page open to long and just refreshed it to get it working again.
I think it would be cool if your chapter had some companion site (or oF app) that would animate the ASCII output your code generates in ideone. Having to scroll is completely fine, so this is wish list type stuff, but being able to copy+paste the output into a textbox and then watching it move would be pretty cool. (Esp for your prime "random" generator.) An alternative might be to just include a few animated gifs.
I think a couple sections could use a conceptual introduction before jumping into code. The functions section comes to mind. It wouldn't require more than a sentence or two talking about what a function is, even if it is just from an english dictionary perspective. It would help orient readers for what is coming next. Same idea goes for the Variables (part 1) section and for the looping section.
Your email to the ofBook list mentioned cutting signed/unsigned and leaving out bitwise operators. That seems fine to me, and I take the silence on the email front as confirmation from the rest of the group? There could be a section at the end of the chapter where you just show some syntax, drop names/concepts and say where to go to find more info. That would arm readers with enough knowledge to feel comfortable diving into those things should they come across them in someone's code.
I feel mixed about the twitter thing since it feels a bit forced and transparent in that it is just about promoting ofBook. It might feel more appropriate in a place like at the end of your ball animation where you ask the reader to tackle some extensions. Or if you were to suggest they design their own random functions and then tweet a link to their ideone code (or a screenshot/gif of their stdout). Etc.
You jump into discussion about compiling and precompiling pretty quickly, which makes sense, but it could benefit from a simply flow chart thrown in there. Something that shows what happens to your code, so that newbies who aren't familiar with compiling have some visuals to grab on to.
For your namespaces analogies, the 3rd grader bus paragraph had plenty of character, but I found it distracted from the point. Maybe you could merge that seat space conflict analogy with your second namespace analogy by focusing on school buses. Multiple buses: there can be people with the same name, but on different buses, etc.
I think the namespace section points out a tricky balance you are trying to strike. In namespace, you are referencing things like
ofBackgroundandglBlendModefor the benefit of advanced readers, but also trying to not overwhelm readers who don't yet know what a variable or function is. Another example of this is Fig 10 where you are introducing types and functions before handling variables. You've set up a flow where you explain every line in the hello world code before really getting into variables.One approach to tailoring that balance to beginners might be to lead the chapter with variables (logic of single lines of code), then work your way into functions (chunks of code), then all the other goodies like precompiling, namespaces, etc. That would just require letting the reader know to ignore
#include <iostream.h>,using namespace std;for the moment and just focus in on what is happening within the{ }. Then the concepts reveal themselves in a way that allows them to build upon each other (or at least, that's how I imagine it happening in the brain of someone just learning to code).Anyway, those were the big notes that I wrote down while reading. I'll throw in some inline comments into your chapter for smaller things. Again, chapter is great so far!