:O this is DAMN smart, really.
I've seen a pretty cool documentation system for (I think) Ruby where you could annotate tests with special comments and pieces of code like this would be pulled into documentation when you generate it from some markdownish format. In C world you'd surround a piece of code with /* +doc-foo */ ... /* -doc-foo */ or whatever and then putting magical [code:foo] in your documentation would fill the spot with code. It's usually obvious that code (whether this comes from sample, unit test or the product itself) doesn't match the narrative in your documentation, even if you just skim it. I plan on rolling something like this in our driver at some point in the future.
I partially disagree on comments, however. Often functions have block sequences that does something, and a simple comment line that says "this does this" before each logical block is cool, especially on long functions (which are not bad, that way).
This only works if you have tight code review process. Otherwise comments will rot.
but I miss (7) - what do you mean?
Conventional wisdom goes like this: unless some suit tells smelly devs what to do, they'll destroy the business in a second. But the reality is that most of the developers these days have survived several successful and/or bombing release cycles and they understand what makes the product (and hence the business). We all have mouths to feed (our own at the very least) so we do care about the end product (which is your business) and not just about some religious BS that's so often attributed to developers. Sure, we're 100% rational only 95% or the time
but if you're writing and playing games for some time, if you're in data storage business or you're in web development business for some time, you know perfectly well what works and what doesn't. Most of us, given a chance, won't spend 10 years on perfecting something that was good enough after a year or two. By the same token if something is lacking, we'll ack that and spend more time on getting things right. I've got this feeling that not every suit understands that, or the business itself. This is probably the main advantage of Imagination over other places I've worked at (or decided not to work at).
This is a graphics technology forum, so we can expect people to care about the width of their variables, as they are likely writing the variables to GPU buffers or CPU side crunching the values using VMX/SSE/AVX/NEON vectors (which need special intrinsics for data loading/storing). I would argue that graphics programmers bit pack even more than embedded programmers (and consoles also can be considered as embedded systems). My code has lots of types that specially state how many bits will be used. uint32_t, uint16_t are common (and also types like Half, UDec3, Dec3N, etc that have specific bit packed patterns that must match the GPU presentations). However I still don't see any reason to for example name my uint16_t variable with some specific Hungarian prefix. That doesn't make my code any more readable. If my variable has some specific purpose, like being a bit mask, I name it accordingly (uint32_t maskRed).
It doesn't make my code any less readable either. [1] But I can easily spot problems during code review when someone takes u32 and uses RegWrite64() with it (the opposite would be flagged by the compiler, sure). Either we're writing more than we need or the data we have is wrong. In a perfect world if would be impossible to introduce this kinds of problems into the well maintained code. But I'm not writing from scratch - I maintaining and extending legacy code of varying quality. Some of these problems come from the fact that, say, logic changes around how we use certain existing structure and during code review we find that variable width was already wrong, it just never bit us in the ass.
[1] I'm not going to get into religions wars about that's "clearly" easier to read or write; we're paid to write and - most often - read code, so if someone doesn't like either of actions because notation offends them, he or she should change the line of job
C++ is good for low level code. Templates make it possible to combine fast code (compile time instead of run time) with better maintainability. For example templated vector swizzles produce better code (more readable and definitely faster) than any C equivalents. Also compile time polymorphism is much better for performance (or memory) critical code than run time polymorphism (= virtual functions).
It's hard to find competent C developers but it's even harder to find C++ ones. I'd rather use the most straightforward C code possible than use C++ and risk that someone who'll be maintaining this down the line will have to understand templated vector swizzles I've added. In general I'm not a huge fan of languages that let you build dialects of themselves. This raises the already high bar of entry for the field I'm in. On top of that I'd have to change expectations for C++ developers WRT runtime behavior. Exceptions in the code are a big no-no, both in drivers and most of the game code. You may take that as an obvious element of game development, but it's not an obvious element of C++ development. Mike Acton proved that at CppCon recently.
In the perfect world where only the most talented developers join your team I'd be all for smart code. But that's simply not the environment we (well, I) work in so IMO obvious is better than smart. I'd love to work with people smarter than me that'd prove me wrong (hey, some of the ppl around here in fact rock and I learn a tons) but that's simply not something I think business can afford right now.