Declare overriding functions override.
I've drafted training slides for this guideline, and I'd like you to take a look and let me know what you think. (Links are at the end of this post.)I don't normally ask for public feedback on material in the form of training slides, but in this case, I'd like to know what you think about some formatting decisions I'm in the process of making. I don't want to put a lot of effort into a manuscript only to find out later that I botched my choice of formatting options.
For over a decade, I've used a proportional font for my code examples. Such a font uses differing widths for different characters. An "m" is much wider than an "i", for example. This has the advantage that I can get a lot more characters on a line, which is important when I'm trying to shoehorn commented code into pages or columns of relatively narrow width. It has the disadvantage that most programmers use a fixed-pitch font (one where all the characters are the same width), so the code I publish doesn't look like what they see in their daily work. In the example I'm making available, I'm using a fixed-pitch font, e.g.:
Question #1: Do you have a preference which is used in the technical material you read?
Whenever I've had multiple colors for code at my disposal, I've used blue for "normal" code and red as a highlight color (see "const" in the code examples above). Setting aside the specific color choices (which have drawbacks, both for color-blind readers and when printed on monochrome printers), the key point is that I've used two colors for code. An obvious alternative is use multiple colors to syntax-highlight the code, then find another means to highlight important sections. One approach is to mimic highlighting pens by using yellow as a background color. This is what was done with my Universal References article at isocpp.org:
Another approach is to use bold face to indicate highlighted code sections. Here's that approach applied to the first code fragment I showed above:
- One color for "normal" code, a second color for highlighted code.
- Syntax-colored code with yellow highlighting.
- Syntax-colored code with bold highlighting.
override." It's available in two versions:- Fixed-pitch code font, blue "normal" code, red highlighted code.
- Fixed-pitch code font, syntax-colored code, bold highlighted code.
Please let me know what you think about the formatting choices I've described. Of course, I welcome comments on the technical content, too :-)
Thanks for your help with this.
Scott
49 comments:
I think the first version is better. Only two colors, no bold and other weird noises. The fixed font helps a lot to the readiness. Its simple, and does the job.
I'd (vastly) prefer the fixed font. The eye doesn't actually have to *read* all the glyphs and still know what's there, due to conditioning.
(It felt as though I was reading code for the first time in proportional font)
Also, I'd prefer the simple colors (red on blue) because (on slides) it works effectively to draw attention to what's relevant.
The yellow marker highlight is painful for me (and might not work well with beamers and ambient light)
My $0.02
Font: The fixed width font is nicer, the proportional width font seems too crowded when compared with the fixed font. The choice of fixed width font is also excellent.
Highlight: If several examples have a lot of code, I would lean toward highlight. If most are small, the bold is easy enough to spot.
Color: Again, I prefer the syntax-highlighted examples if there is a lot of code. For short examples, single-color is fine.
#1. No preference either way -- as long as the code font is different to the text font.
#2. I definitely prefer the blue/red over the other two options, with the bold option being my least preferred.
Depending on the printing/projection quality I think the bold font may not actually be very bold! Scanning quickly through the PDF, for me it's remarkably easier to see what you're wanting to draw the reader's attention to with the red/blue difference.
Re the technical content for this item, it was great to see a new Item, even in draft form. :-) It seems to me, though, that the "Fun with override" slide, while cool and interesting to C++ language geeks, IMHO doesn't seem necessary/appropriate for an Effective C++ audience, at least going by the technical level that I remember from when I last read the series. :-)
Q1: Fixed font looks better in this small example. I guess it it because I'm used to it, so I can read it faster.
For longer pieces of code I'm not so sure. If you have to do a lot of line breaking just because of the font - that would be more difficult to read - and be annoying.
So if all code examples are as small as the ones in the given slides, fixed font is better.
Q2: In the slides, bold was difficult to spot as the highlighted code.
Background colored highlight (in yellow at least) makes it difficult to read the sentence in one go.
How about a less intrusive variant like underlined? Then you could still use syntax-highlight.
If not, then I would prefer the two color variant.
I think I prefer the fixed width font as well (although I just picked up my Effective C++ 3rd Edition that lives on my desk - thanks by the way - and the proportional font in there is also pretty easy to read).
I feel more strongly about the highlighting. The bold doesn't draw my eye very well, and the highlighter pen is just jarring. While I do like the syntax highlighting, I could live without it to get a separate colour for picking out key words (not keywords).
Q1: fixed-size font is definitely easier to read.
Q2: I'd prefer two-color variant. Bold is difficult to spot.
My preference is definitely for fixed-pitch font; it's what I'm used to reading code in, and is noticeably faster for my brain to parse.
As for as the colouring goes, although I prefer the syntax highlighted version overall, the bold style is ineffective at drawing the attention; the 2-colour contrast does that very well. I'd like to see syntax highlighting combined with a background highlight for uh..highlighting.
Technical content - I agree with Neil on the 'Fun with "override"' slide, as it doesn't seem particularly beneficial. Although not a keyword, I'd hope that anyone who wishes to write good code enough to be reading EffC++ would instinctively avoid using it in new code! Perhaps worth making mention that it isn't a keyword and that legacy code using it as an identifier is still valid.
Question#1 : My preference is for a fixed-pitch font as it's how I view code in my editor. I have very dog-eared copies of Effective and More Effective C++ (not to hand at the moment) is the font used in those proportional?
Question#2 : My preference is definitely for syntax colour with bold for highlighting, again this is just for consistency with editors.
I love the proportional fonts when the code stay well formatted (indents, ...). It saves precious screen space on 7 inch devices.
On paper, computers and tablets multi-colored code looks great. It provides all the advantages you enjoy with modern IDEs. On Kindles I've had problems reading anything else than black, though. Since I am using both real Kindle ebook readers and Kindle ebook apps on tablets I have a hard time what color scheme to vote for ...
The fixed-space font is way better. With the proportional font, half the letters blend together.
I also think that the red on blue (or similar schemes) works best for highlighting. It's much more effective than the other, as long as it's not too long. Else I'd want syntax highlighting.
#1. No strong preference, but I'm leaning towards the proportional font.
#2. Definitely the two-color scheme. Adding syntax highlighting draws attention away from the parts you want to highlight.
My personal preferences:
Question 1: fixed-pitch font, definitely! I agree that this reduces the amount of code you can put on a slide, but look at it from the positive side: it forces you to be brief and concise.
Question 2: Syntax-colored code with yellow highlighting. But maybe a slightly less bright yellow that does not shine so much in my eyes... ;-)
Regards,
Bart
- Fixed-pitch font
- Syntax-colored code with yellow highlighting
- Never use red
- Never bold code
#1 Fixed-width. Proportional is so alien to me that it distracts from trying to read the code.
#2 First choice. When I'm reading your examples I want to look at the thing you are highlighting first, and then work out from there. This is the quickest option for finding the part that you are describing.
I prefer fixed font, as it seems to help when skimming the code. It's easier to skip the unimportant stuff by just recognizing the common patterns/format, rather than actually reading the code.
As far as color, I love syntax highlighting when coding, but when being presented important information in an instructional context, I want the important info to really stand out. I think keeping all but the important code the same color, while highlighting the point of interest with another font color or background is the best way to accomplish this. I don't think the bold text stands out enough to differentiate. Also, I use bold for certain syntax elements while coding on a day-to-day basis, so I tend not to pay as much attention to it in the learning material.
I prefer "Fixed-pitch code font, syntax-colored code, bold highlighted code."
But as I read more and more on kindle e-paper. I'll love "Fixed-pitch code font, bold highlighted code - italic light color for comments."
Comment differenciation is one of the thing I miss the most on technical e-book. The Main problem is when a comment go to the next line on ebook (after a change of font size) sometimes it's difficult to differentiate the comment after the line break and a normal instruction. Specially when the comment talk about object or members.
Q1: Definitely prefer fixed size font.
Q2: Just two colors please, the second set of slides w/ the syntax highlighting had too much going on. the yellow highlighting is painful to read.
#1: fixed font
#2: your slides with "red highlighted code" are more readable to me. Bold highlighted code is less focusing, bold font is less noticeable to me. IMHO you can use bold to highlight structure (keywords, important variables, ...) to improve global readability of a piece of code, and red to highlight code involved in the current problem.
I like the way your universal references paper was formatted.
@David Corne: In the first two editions of Effective C++ and in More Effective C++, the code font is fixed-pitch. In the third edition of Effective C++ and in Effective STL, the code font is proportional.
@Anonymous: Regarding "never use red," can you please elaborate on why?
Definitely fixed width font.
The bold did not stand out enough for me, but the color highlighting will get lost in a monochrome display, such as a printout (don't use the color printer/colored ink unless I need to), or a e-ink display. Perhaps a combination of color and the underlining that someone suggested would work there.
The suggestion for comments to be in fixed width italics would also be useful for when the comments wrap.
It is my opinion you should use a Fixed-pitch code font, blue "normal" code, red [and bold] highlighted code.
-I believe most people identify a fixed pitch font as code, so despite the fact that it takes more space I prefer the look of code.
-Using two colors (i.e. blue and red) helps highlight the targeted example code. I would also bold the targeted code to further help with monochrome display and print and color blindness.
-The yellow highlight looks garish to me.
1. In larger code samples (4+ lines) I think the proportional font is harder to read because it squishes up more in the same space. That being said, I think I can get used to either, so the difference is minor.
2. Syntax-colored code with yellow highlighting. The bold is too subtle for me.
I like syntax colored code with *red* for highlighting. Basically in your two-color example everything is blue unless its highlighted red, but I think it would look fine and more clear to use use blue/teal/black for non-highlighted code. Bold is harder to find at-a-glance than red is. Blue/teal/black offer better readability than just blue.
I also prefer fixed sized font on screen, but variable sized is fine when on paper with a good font.
#1: I find fixed-width fonts easier to parse, probably because that's just how I usually view code.
One good reason for fixed-width fonts: if the choice is between you spending time fighting with a variable-width font (to get indentation or special characters looking good) or creating new and interesting content, I'd prefer the new and interesting content.
#2: I like the syntax-colored code with yellow highlighting. The level of bolding that you demoed doesn't really draw attention to the differences that you want to point out, so that's no good. And having a small amount of syntax highlighting makes the rest of the code much easier to parse.
I use a proportional font with syntax highlighting when working, so that is what would appear most natural to me. However, most code is presented in a fixed font, so I find that easy to read too, and that's probably what most others are used to.
Bold face doesn't stand out very well in code examples. I prefer a bright colour (e.g. red vs blue/black for normal code), but if you're going to use syntax highlighting then a coloured background might be better unless you have a bright colour that is not otherwise used for syntax.
I prefer a fixed point font with syntax highlighting. For highlighting the example, I'd rather see a different fixed point font (something visually quite distinct), italic, underline, or preferably a dotted outline around the code you want to draw attention to.
I don't think the bold highlighting stands out enough (not even close actually). If you really want bold then you'd have to make it really bold.
Q1: fixed-pitch font, because this is what programmers are used to see and therefore is easier to read.
Q2: Syntax-colored code with yellow highlighting, again since syntax-highlightning is what programmers see on a daily basis. Mono-colored code in books is hard to read
Suggestion for a "Q3": I don't like the java-style brace indenting, because it isn't symmetric. And since I don't use it, this style is harder for me to read on books.
I'm not sure what the general programmer preferences is, but after syntax-highlightning, this is the next important style consideration. Maybe you could do a poll on this one, too?
void foo {
};
vs.
void foo
{
};
@Zenju: Thanks for you comments. Regarding placement of braces, I'm afraid you're going to have to live with my style, sorry. The code has to look right to me, too :-)
@Scott: This is outrage - but fine, I'll grudgingly accept this style of braces... :) you somehow seem to know that I'll buy your book anyway...
@Zenju: Well, every style that is not the one you use is an outrage, right :-)
1) Fixed-pitch font, definitely (smaller is okay to fit more...)
2) Code: Syntax-coloured
Highlighted code:
- *Not* bold. Doesn't stand out enough
- Highlight ok but use a more mellow color than yellow
Personally I like following look for highlight:
- Lightly colored (pastel / low opacity)
- Slightly rounded corners on the highlight
- Subtle border (same colour as highlight but slightly darker)
That's pretty specific, I know, but I think it looks great! The rounded corners can even work for "blobs" of highlight that span multiple lines of code.
(I Must have seen this look somewhere but I can't remember which program.)
@Scott: I think I have the perfect solution. Since your new book will be flexible with regards to target platform, there could be the following online service: You upload an Astyle configuration file and download the final pdf of your book. - This can't be that hard to program (but I'm not volunteering!). Your book would have the best code formatting of all C++ books out there. And one of the problems that really matter to people would finally be solved.
Soliciting for opinions tends to draw the strongest of opinions...
Q1.
I find both equally readable.
Q2.
I have some difficulty noticing the bold text. In that style, the varying colors are already drawing my attention.
The other two styles - yellow highlighting and the style you've historically used - both seem digestible to me.
I definitely prefer the simple red/blue coloring - does a good job of highlighting what is different/important without clutter.
No strong preference on fixed vs. proportional, so I'd say go ahead with proportional if it makes it easier to fit stuff in...besides, it'll give the book that 'Effective' look and feel =)
@Zenju: In principle, the idea of generating a custom presentation of a book based on user preferences (e.g., an Astyle configuration file) is one I like. I even discussed this idea in a presentation I gave at the TOC Conference in 2009, though I was focusing more on color choices than formatting. Technically, it should not be that difficult to implement, but I think it's currently beyond the state of the practice in general-purpose technical publishing. I've been talking with the publisher of my past C++ books about how to approach Effective C++11, and the notion of treating digital versions of books as primary (instead of as secondary versions derived from primary print versions) is something that is still considered rather experimental. With that in mind, I suspect that setting up the infrastructure needed to support on-the-fly book formatting is not something that's likely to happen soon. On the plus side, when such capabilities are available, I see no reason why the manuscript I plan to produce would not be in a good position to take advantage of them.
The world of publishing is changing, but the movement isn't as fast as I'd like. If you know of publishers who are offering anything like the personalized formatting you've proposed, I'd be very interested to hear about it.
1. Definitely the monospaced font.
2. As for the highlight, I sort of like the idea with the yellow, however I have a hunch that printed that would come out quite bad. So I would say the bold option, however I would also advise for the usage of the light grayish background color, so you can see on a glance what's code and what's explanation.
The fixed width code is much easier for me to read; I just expect code to be fixed width.
For the highlighting, I prefer syntax colored code with bold. The yellow highlight is just to garish to my eyes, and the syntax coloring really helped break things up when I was going through the two examples.
I much prefer code to be in a fixed width font.
As for the colouring: I use a B&W Kindle, so I don't mind as long as it's still visible there.
I prefer two colors. The highlighting is too jarring for me to read. I don't mind the proportional font. The use of bold seems the least obvious and would be far too easy to miss. Your code snippets tend to be fairly brief, so the syntax highlighting doesn't seem all that helpful.
@Zenju : or PDF could just support styles dynamically so you can (re)set a given file on the fly even after it is produced.
proportional code blocks look awkward. Fixed width with a bold highlight should be ok or a gray shade.
By the way, a formatted version per use taste sounds good ;)
For your samples: fixed, and font color change.
But that doesn't mean these choices are necessarily the best. Other alternatives might be better.
In particularly, the background color idea is probably better than the font color change, if only the color change is more subtle (but still noticeable). The yellow highlighting is so extreme that it makes it difficult to notice anything just beyond the edges of the highlight (for me, anyway). But glaring extremes are rarely as pleasant as merely "readily distinguishable" changes. That goes for font color changes as well, but since there is not as much pixel area, the change can be less distinguishable there. If you go with a thinner font, the font color change has to be even greater to afford the same effect. I think that's a good reason to use background color instead.
Similarly, it isn't (IMHO) the fixed-width aspect of a fixed width font that is important. Rather, it's clarity and accuracy of perception. Most proportional fonts can put things too close together and make it hard to distinguish parentheses from curly-braces (or O from 0, etc.). But this does not have to be the case for all proportional fonts. I strongly suspect that with the right choice of a very clear proportional font, the code could be even more clear and palatable than the best fixed-width available. But I cannot suggest any existing fonts that might fit the bill. Maybe they're yet to be invented.
Whether you find such a proportional font or not, I think it is still a splendid idea to use proportional font for comments. Proportional is a more readable change than simply switching to italics. Italics are hard to read. But you need comments to look different. So I say use a standard proportional there even if nowhere else.
The other reason it is important to use fixed-width when writing code, and then reading it afterward, is that you want to control the vertical alignment of similar items (not just where lines begin). But in this case, the font will be permanently fixed and you can arrange that alignment in every case for the specific font in use. Thus it shouldn't be a big problem; just some extra work for you.
@Zimbot: Can you please elaborate on your final paragraph (regarding controlling vertical alignment)? I'm not sure what you mean here.
Fixed width font. Having begun coding in character consoles with Turbo Pascal editor, this should be considered as bad habit that must change.
Syntax Colored code with colored highlighting, unless multiple statements from an advanced library are grouped like 3 to 4 lines of OpenGL in which case colorfulness would be distracting.
Fixed-pitch code font, syntax-colored code, bold highlighted code felt more comfortable, but red had strong imprint if you really want to teach stubborn me a thing or two :D
Post a Comment