How Not to Write a Programming Book

1.3.2009 18:51 | Přečteno: 1647× | psaní | poslední úprava: 6.3.2009 10:51

By this post I would like to start a longer series about common mistakes made by authors in programming books. If I waited until I was happy with the thoughts expressed in the post, I would most probably never finish a single one. Therefore I will intentionally publish the text a bit raw and maybe return to the interesting thoughts in subsequent posts or even edit the post after publishing. I will start with what seems to be my favourite topic lately, with bogus code samples.

Bogus Code Samples

Programming books are full of code samples you would never write in the real world (at least not in your sane mind). Almost nobody takes the pain to handle the error conditions. Is that tolerable? Checking the error conditions would make the code harder to read, especially in the lower languages, where you cannot take advantage of exceptions. And the code is often repeated in the book, which would further complicate the issue. On the other hand, almost everybody learns to ignore the return values and exception conditions this way and only starts doing otherwise after they burn themselves bad in the real world. This would probably require a deeper thought; I wanted to talk about something simpler – contrived sample code. Consider this:

void sum(int x, int y, int& z)
{
    z = x + y;
}

This is a real example taken from an introductory programming book (!), the code is meant to illustrate passing arguments by reference. In practice one would certainly pass the sum back using the function return value. Passing arguments by reference would be better illustrated by something like this:

bool read_data(int& data)
{
    if (everything_goes_fine())
    {
        data = …;
        return true;
    }
    else
        return false;
}

This is also a bit contrived: Would you call a function read_data? Would you signal success by returning true? Shouldn’t this better be solved by using a pointer? I am not a C++ programmer and made this sample up on the spot without context, so that I cannot answer these questions right now. But it would certainly be better if the autor could illustrate passing by reference using some example that can’t be solved simply using the function return value. Do not cheat the readers, do not pretend that a problem is harder than it really is.

Another example of what not to do, again from a real programming book:

#include <iostream>
using namespace std;
int main(void)
{
    int x = 0;
    while (x++ < 5)
    {
        int y = 0;
        while (y++ < 5)
            cout << "X";
        cout << "\n";
    }
    return 0;
}

This is a while loop misused as a for loop. Of course you can reason that the author simply wishes to illustrate a point, like passing arguments or comparing two cycles. I think that contrived, unreal examples are bad in programming books, especially if not explicitly marked as such.

Just as a beginning speaker of a natural language often cannot detect irony, beginning programmer cannot tell “real code” from the “sample code”. Autors sometimes remark that the code sample is only meant as an example and would be written otherwise in practice. This is almost always just an excuse. Of course, writing production-grade code is not always possible in the book, but does it really make sense to write a book full of code that nobody would write in practice?        

Komentáře

[dad]

olsó í glaub ned, dasse Sinn mocht, hier Beitróg ina Frendspróch zu póste.

Das war Schwäbisch.

[zde]

Ich auch šprice dojč! :)

[dad]

je mozne (podle toho šprice) , ze jste se ucil nemcinu od nejakeho polaka?

[freshmouse]

Nebo od někoho z východní části naší republiky. Jak jsem četl "šprice", znělo mi to jako "piče"...

[zde]

Ja ja, piče schön!

[CET]

heh, pri cteni nahlas mi to zni dost jako svycarska nemcina:)

[dad]

ten dojem je spravny, co vim, tak obyvatele jizniho badenska-wuerttemberska jsou jedini Nemci, kteri svycarum rozumi, neb obe jazykove skupiny hovori stejne hroznou hatmatilkou ...

[Cestmir Houska]

A co Tirolaci? Podle me mluvi taky dost podobne.

[houska]

co? a pro oba je to rodna rec? clovek kterej mluvi nemecky nerozumi jinymu cloveku kterej mluvi taky nemecky?! kam jsme se to dostali ...

[Fluttershy, yay!]

Hoch němčina a Schwyzer němčina jsou něco jiného. Tak jako BrE a AmE.

[houska]

nerekl bych ze si american s britem/australanem/indem/JARanem nepokecaj ...

slo mi o to jestli ty jazyky jsou od sebe opravdu tak daleko ze si nerozumi ...

[dad]

v nemecke televizi jsem videl svycarske zpravy, jsou povetsinou z titulky, jinak tomu skutecne vetsina Nemcu nerozumi, znam jednoho Svycara z Basileje a je to tak, ze se musi skutecne silne koncentrovat, kdyz chce mluvit spisovnou nemcinou. Nekteri starsi svycari to pry ale nedokazou vubec. Jina vec je, ze samozrejme nemecky svycar rozumi spisovne nemcine.

[trekker.dk]

nuqDaq 'oH puchpa''e'ě

[kralyk z abclinuxu]

Ní thuigim. Tá tinneas cinn orm. Póg mo thóin... /Gaeilge Éireann/

[2009]

英語を読むことができない

[dad]

presne taky muj nazor.

[YYY]

Tak na tohle jsem opravdu potreboval google translate

[2009]

Je to copy-paste z translatora, takze to moze byt zle.

[Fluttershy, yay!]

Ano, je to špatně.

[2009]

Malo by to byt spravne:

eigo o yomu koto ga dekinai - nemozem citat Anglictinu

[Fluttershy, yay!]

Gramaticky špatně... nebo neumím číst? Nehledě k tomu, že máš chybu už jen v té transkripci do latinky.

[2009]

Co tam je gramaticky zle?

Niektore znaky sa prepisuju roznymi sposobmi. Doslovny preklad tej vety je: Nemozem robit citanie Anglictiny.

[2009]

Tych prekladov je viac:

eigo wo/o yomenai

eigo wo/o yomemasen

[Fluttershy, yay!]

+/-

[Fluttershy, yay!]

Musím si nahodit nějaké lepší písmo, takhle jsem tam vůbec neviděl nigori.

[andree]

slusne

[microcz]

+1

[kralyk z abclinuxu]

Ty první asi 4 znaky mi přijdou na Japonštinu nějaký složitý, skoro jak čínština. Je to normální japonština? [japonsky neumim ani ň ]

[Andrej Herceg]

Prvé dva znaky sú rovnaké v japončine aj v čínštine (a znamenajú to isté), tretí znak je hiragana, takže určite to je po japonsky a nie po čínsky (a ten koniec vety je typická japončina). :)

[Fluttershy, yay!]

Ještě dodám, že pro angličtinu se používá katakana イングリッシュ.

[kralyk z abclinuxu]

Hm to je zajímavé ... sem vůbec nevěděl, že mají společné některé znaky ... a to se takle běžně používá, nebo to je výplod strojového překladu?

[Fluttershy, yay!]

Ten překlad se mi nezdá. Každopádně v japonštině se běžně používají čínské znaky (kanji), které ovšem samozřejmě mají japonské čtení, pro gramatické záležitosti nebo přepis komplikovaných znaků se používá hiragana (slabičná abeceda) a pro přejatá slova se používá katakana (jiná slabičná abeceda) --- obě tyto abecedy jsou fonetické, nebo jak se tomu říká.

[Tomáš]

Zdá se to jenom mně, že v příkladech chybí dereference pointeru? Tedy *z = x + y, případně *data ... .

[zoul]

Reference jsou v C++ v podstatě automaticky dereferencované ukazatele, takže nechybí:

#include <iostream>
using namespace std;

void change(int& what)
{
    what = 42;
}

int main()
{
    int foo = 0;
    change(foo);
    cout << foo << endl; // 42
    return 0;
}

Jinak díky za první příspěvek v tématu

[Michal Kubeček]

Ono je jednoduché kritizovat, že autoři učebnic neošetřují chybové stavy. Ale když si zkusíte nějaký učební text napsat, zjistíte, že to zase tak jednoduché není. Protože když budete chtít realisticky ošetřit všechny možné chybové stavy, několikařádková přehledná a názorná ukázka se nafoukne na několikanásobek délky, stane se naprosto nepřehlednou a čtenáři unikne podstata. Totéž platí pro ty nerealistické příklady: některé věci jdou demonstrovat na příkladech ze života, ale často ty reálné příklady opět trpí nenázorností a nepřehledností.

[zoul]

Však jsem psal, že zrovna to hlídání chybových stavů je ošemetná věc. A stejně tak souhlasím s tím, že některé příklady z praxe jsou nepřehledné a nenázorné. Je to otázka rovnováhy a vhodně volených příkladů – nikdo neříká, že psát knížky o programování je lehké. Od mnoha autorů jsou umělohmotné příklady bez kontroly chyb jen alibismus, to mi vadí. Například SICP hloupými příklady netrpí ani v nejmenším, podobně Velbloudí kniha. Pokud se někdo rozhodne psát knihu, měl by být schopen vybrat nebo napsat příklady na úrovni.

[Ladicek]

Například SICP hloupými příklady netrpí ani v nejmenším

SICP jsem četl a je to úžasná knížka. Klíčový je ovšem použitý jazyk: v C++ by podobné příklady měly několikanásobnou délku, a to bych nechtěl vidět pátou kapitolu. Když jsme ovšem u toho: můžete doporučit nějakou opravdu kvalitní učebnici C++? Český jazyk vítán V poslední době uvažuju nad takovým cvičením, na které se právě hodí nějaký nižší jazyk. Nejradši bych se u toho aspoň trochu naučil C++, i když D vypadá taky super

[Ivan]

Vyborna knizka je www.amazon.com/Modern-Design-Programming-Patterns-Depth/dp/0201704315, jeji ceskej preklad je bohuzel dost tragickej. Vsechny odborny terminy jsou - nekdy i dost nasilne - prelozeny do cestiny, ale na druhou stranu maji vety casto anglicky slovosled.

 

[zoul]

To je pravda, v tomhle ohledu má Scheme zjevné výhody. (Mimochodem, ale to spíš pro zábavu.) V knihách moc velký přehled nemám, ale náhodou mám doma už přes deset let Programovací jazyk C++ od Stroustrupa. Když jsem ho dřív čítal, ohromně se mi líbil, i když jsem skoro ničemu nerozuměl. Myslím, že je to výborná kniha, jen překlad do češtiny (Jaromír Šmejkal, Ben 1997) je bohužel příšerný, na hranici čitelnosti. Originál podle mě stojí za koupi, je to knížka na úrovni K&R, SICP a podobných.

[Fluttershy, yay!]

Mně se líbily knížky od Viria, hlavně ta skripta FJFI o C++. Ale to je něco dost jiného.

[Ladicek]

Od Viriuse (he, to je jméno!) jsem četl Od C k C++ a s tím jsem teda spokojen nebyl ani trochu.

[b*d]

Českej překlad nasazuje všemu korunu. Origianál je lepší. I když je potřeba používat slovník člověk se alespoň naučí klíčová slova pro google. 

int read_data(int& data, int velikost_dat)
{
    int readed = 0;
    for(; readed < velikost_dat ; readed++)
       if ( chyba ) return -2; 
       else ...
    return readed;
}

a máme příklad který se používá a je se smysluplnou návratovou hodnotou (o triku int vs char a EOF bych zatim treba pomlcel). Takže proč vymýšlejí autoři ptákárny a nedávají příklady ze STL?

[Michal Kubeček]

readed???

[kralyk z abclinuxu]

My grammar is gooder...

[b*d]

Je potřeba z Angličtiny odstranit některé zastaralé výrazy. Mladý brit pohledá v Googlu a bude si myslet že je to správně. Pak bude angličtina jednoduší pro celý svět.

 

[cronin]

To tvrdil uz Orwell.