On Technical Books, Accuracy, and "Holier than Thou" pedantic attitudes
Among my other travails in the .NET world, I've been serving as a Technical Review Editor for a couple of upcoming .NET related books.
You see some interesting and occasionally VERY ANNOYING statements made by various authors when you get to review these chapters. It becomes obvious (especially with .NET 2.0 where authors are often "rewriting" their 1.1 books, and more often than not, they aren't adding much new value either) that we are making statements and proclamations out of habit, even when they are DEAD WRONG, simply because some tech reviewer from the previous book didn't catch it.
I'm not naming names, because that's not the point. The point is, authors should take GREAT PAINS to get their facts straight. If I am a "noob" and I buy and read your book and accept information that you give me in the confidence that it is factual, and it turns out not to be so, you have done me an egregious disservice and hurt not only me, but yourself, your publisher, and the rest of the technical publishing landscape.
Last night I got so confused by two related "best practices pronouncements" in a book I'm reviewing that I actually had to write a short program in C# 2.0 to prove to myself that if I pass a DataTable (a reference type) into a method, and modify a column's value inside the method, that the ORGINAL Datatable will be modified! This is one of the most egregious and poorly explained language facts, reference types are passed by reference by default, it doesn't matter if your method is getting a "COPY" of the reference, the point is if you modify the object inside the method, YOU ARE MODIFYING THE ORIGINAL OBJECT. Period! You can put the "ref" keyword in front of the parameter, or leave it out. It won't make a bit of difference.
Just a word to the wise:
If you are an author, take the time to get your facts straight, and once you have, be sure that you can explain them very clearly.
if you are a reader, don't trust everything you read!
You see some interesting and occasionally VERY ANNOYING statements made by various authors when you get to review these chapters. It becomes obvious (especially with .NET 2.0 where authors are often "rewriting" their 1.1 books, and more often than not, they aren't adding much new value either) that we are making statements and proclamations out of habit, even when they are DEAD WRONG, simply because some tech reviewer from the previous book didn't catch it.
I'm not naming names, because that's not the point. The point is, authors should take GREAT PAINS to get their facts straight. If I am a "noob" and I buy and read your book and accept information that you give me in the confidence that it is factual, and it turns out not to be so, you have done me an egregious disservice and hurt not only me, but yourself, your publisher, and the rest of the technical publishing landscape.
Last night I got so confused by two related "best practices pronouncements" in a book I'm reviewing that I actually had to write a short program in C# 2.0 to prove to myself that if I pass a DataTable (a reference type) into a method, and modify a column's value inside the method, that the ORGINAL Datatable will be modified! This is one of the most egregious and poorly explained language facts, reference types are passed by reference by default, it doesn't matter if your method is getting a "COPY" of the reference, the point is if you modify the object inside the method, YOU ARE MODIFYING THE ORIGINAL OBJECT. Period! You can put the "ref" keyword in front of the parameter, or leave it out. It won't make a bit of difference.
Just a word to the wise:
If you are an author, take the time to get your facts straight, and once you have, be sure that you can explain them very clearly.
if you are a reader, don't trust everything you read!
There's definitely technical errors in pretty much every tech book I've ever seen, but it is disconcerting when the fundamental concepts aren't grok'd by the author.
ReplyDeleteThere's the argument of making such works more communal/wiki-style entities to help catch such situations (a view of the current authorship as too ivory tower, ala CatB), but that's probably overkill - good tech reviewers (like yourself, it sounds like!) can help catch the lion's share of issues.
I agree, but isn't it true that if you pass a reference-type argument with the value of Nothing in ByValue, and you instantiatie that variable in the method,the calling varibale stays Nothing, because the reference type variable is actually a pointer to something and because it's a ByVal, it's a copy of the calling pointer.
ReplyDeleteTo have the calling variable see that object instance that you created inside the method, you need to pass the variable in as a ByRef.
Jens
Interesting Comment about wiki-style. In fact, an author friend of mine who has successfully self-published his last book (because the original publisher "dumped" him in mid-stream) says that in 5 years, printed books will be obsolete. Books will, instead, be "live web sites / wikis".
ReplyDeleteJens,
ReplyDeleteRegarding the comment about "Nothing" being passed into a method ByValue, my post was specifically directed at the C# language. VB.NET is an entirely other animal, and thankfully for the last few years I haven't been forced to deal with it much.
"if you are a reader, don't trust everything you read!"
ReplyDelete...
I hate to say it - but it's true. There used to be a time when you could trust authors...
Editting is a lost art.
ReplyDeleteBeyond checking that words are spelled correctly (even if they're the wrong words -- homonyms, etc), it's as if nobody's bothering. Cursory reading reveals big problems before you even get to the technical matter, even in the respected houses.
Amen. I hope that authors will not loose sight of the importance of excepting this important fact, and why its affect is more important then there writing technique.
ReplyDelete