Hacker News Reader

I am sure that for you it was a pile of tautologies and common sense, but I think most people graduating with an undergraduate degree would benefit from reading Code Complete as they start their career.

I have to admit I thought it worth the time to read. It is an easy read. There are certainly books on this list that provide >10x the value, but take >10x the effort to assimilate.

  >> It tries to teach stuff that is best learned through experience.

Experience is a harsh teacher.

To quote the pragmatic programmer, "bullets are cheap".

An engineer building a bridge doesn't have an easy way to just try it out. Someone hacking together something at home, or an internal facing product at work can learn by experience.

"Experience keeps a dear school, but fools will learn in no other, and scarce in that" -- Benjamin Franklin

> My advice is to learn to use your favorite editor with a TAGS file, then go navigate through a large open source project, and extend it in some minor way. That's more profitable than enduring any book on "design".

This is the truth.

On the other hand, I learned from experience that people do not take this advice when you give it. Maybe plunging into large codebase is daunting, I don't know. Now I give them http://www.aosabook.org/en/ and tell them to choose an interesting project and then read it.

That book looks excellent - perhaps if all large open source projects included something similar, they'd get more contributors? I suspect that jumping into code with no overview of it's structure is going to be slower than if you have a clear framework to hang things on, which might explain the reluctance.

Their follow up book also looks good: http://www.aosabook.org/en/makingsoftware.html

Code Complete is a great book, and I don't think there are any other books out which cover the nuts and bolts in such a thorough way.

I also recommend "Rapid Development", by the same author. It sounds like a fuzzy, Agilish cliche, but a more accurate title is probably "How not to fuck up your project." All of the usual bugbears are there - technical debt, creeping requirements, gold plating, etc.

> Code Complete is a great book, and I don't think there are any other books out which cover the nuts and bolts in such a thorough way.

Eh, I don't recommend Code Complete, either, though not for the same reasons as mahmud.

You say you don't know of a book "which cover the nuts and bolts in such a thorough way". I can name one that covers almost the same territory:

Kernighan and Pike's excellent The Practice of Programming.

You could certainly argue that it doesn't cover the same territory in such a "thorough" way, if by thorough we mean "needlessly bloated". The Practice of Programming manages to say, in 288 pages, everything useful that McConnell needs 960 pages to spit out.

The Practice of Programming is the last book I can think of that came out of the old tradition of software books that valued concision and clarity of communication above all else. It's short and precise in the way that "The C Programming Language" is short and precise compared to modern PL books. Code Complete is a product of modern software book marketing; it takes forever to say anything, so that it consumes maximum space on a bookstore shelf, and attempts to justify its price in weight rather than ideas.

I think that's an unnecessarily harsh review. From looking at the table of contents, it looks to me like Code Complete covers a lot more territory, eg. there doesn't appear to be anything on code reviews in The Practice of Programming.

That said, I'm going to have to find a copy of it now and compare them :)

I loved the size of code complete but the brevity of the content itself. I didn't read from cover to cover, but always had the copy on the table and read a chapter each morning.

No, there are new, concise book, though I agree they're rare:

The Art of Readable Code (by Googlers)

http://www.amazon.com/Art-Readable-Code-Dustin-Boswell/dp/05...

Having read both I have to respectfully but firmly disagree.

The code examples in The Practice of Programming are atrocious, and I mean it - they are full of really, really bad naming and arcane abbreviations and thus unreadable code.

How is this for readable and maintainable code? (Random code example from The Practice of Programming, copied verbatim letter by letter)

    /* delname: remove first matching nameval from nvtab */
    int delname(char *name)
    {
        int i;
        
        for (i = 0; i < nvtab.nval; i++)
            if (strcmp(nvtab.nameval[i].name, name) == 0) {
                memmove(nvtab.nameval+i, nvtab.nameval+i+1),
                    (nvtab.nval-(i+1)) * sizeof(Nameval);
                nvtab.nval--;
                return 1;
            }
        return 0;
    }

- Confusing function explanation in a custom format. What is nameval? What is nvtab?

- Missing curly braces in the for loop

- Confusing long lines (line starting with memmove())

- Confusing inline transformations: nvtab.nameval+i+1, nvtab.nval-(i+1) directly in function arguments. What do they mean?

- Bad, bad naming (nvtab, nameval)

- Inconsistent case (nameval vs Nameval)

This is just ONE RANDOM EXAMPLE, mind you. The book is atrocious, I don't recommend it to anyone.

Code Complete is much thicker but that's the only disadvantage. It's not bloated, it's simply more comprehensive, it's consistent and teaches to write actual readable code.

I've never read that book, but I've worked with a lot of C. That code seems perfectly maintainable as an experienced C programmer.

- Confusing function explanation in a custom format. What is nameval? What is nvtab?

nvtab is obviously a name/value table. nameval is an array of Nameval structures. nval is the count of Nameval structures in nvtab.nameval.

- Missing curly braces in the for loop

This isn't required by C. It's an often-debated subject in style guides for C.

- Confusing long lines (line starting with memmove())

How is that confusing? Lines end when you see a ; that isn't inside a set of parens.

- Confusing inline transformations: nvtab.nameval+i+1, nvtab.nval-(i+1) directly in function arguments. What do they mean?

What do you mean, "what do they mean"? (int)-((int)+1) seems pretty obvious. Working with memory addresses doesn't seem a foreign concept.

- Bad, bad naming (nvtab, nameval)

nvtab seems like a reasonable name for a name value table. nameval seems like a reasonable name for something that holds a bunch of Nameval structs.

- Inconsistent case (nameval vs Nameval)

nameval and Nameval are different. If you used consistent case, the program wouldn't work. nameval is an array containing Namevals. Nameval is a struct.

This just seems like a case of you not really understanding C rather than a case of experienced C programmers writing C that other C programmers could maintain.

I had a post with most of the same stuff you said saved for after lunch but you beat me to it with a more precise explanation. I haven't touched C in years but it wasn't difficult to understand the code, though a couple of comments would have made it quicker to parse.

Perhaps this is the effect that high level languages are having on developers - anything that DoesntHaveExplicitNames is classed as confusing and syntax flexibility is seen as wrong. In the web development field, I often get weird looks for writing one line if statement bodies. A ternary operator usually yields furrowed eyebrows for a few seconds. An issue of style over substance, IMO.

Then again, I'm sure that ASM developers looked at C developers the same way.

Probably, the key part of what you said, is "couple of comments". Makes a huge difference if the same convention is on,say, 100,000 LOC, and the people who wrote it didnt give proper comments and left the company! :P

Speaking on naming conventions: This is the name of a class in Chromium source code (C++): 'BufferedSpdyFramerVisitorInterface' . The codebase is that meticulous! For a guy who wanted to learn about browser implementation,and downloaded the codebase,this is good.

These meticulous naming conventions- has it anything to do with using a full-blown ide vs vim?

> These meticulous naming conventions- has it anything to do with using a full-blown ide vs vim?

What would you think that?

If it's because of auto-complete, please understand that this is 2012, and vim is not [just] vi. There are several different flavors of auto-complete available in vim; some built in, some as extensions.

Not to mention that there's eclim for full-scale Eclipse completion and ctags which provides almost the same functionality (though not as intelligently).

C programmer are so used to terrible code that it doesn't even stand out to them.

The thing that sticks out for me is that there's a bug in that code - a syntax error no less - and none of the C programmers commenting seem to have spotted it. (hint: read the memmove line a bit more closely)

I don't think you need much more evidence that the syntax is confusing.

> The thing that sticks out for me is that there's a bug in that code - a syntax error no less - and none of the C programmers commenting seem to have spotted it. (hint: read the memmove line a bit more closely)

That typo was introduced in Revisor's transcription; it doesn't appear in the original. I checked when I first read his comment, 8 or 9 hours ago. It hardly seemed worth mentioning; typos happen and it had nothing to do with his argument.

> I don't think you need much more evidence that the syntax is confusing.

Someone unfamiliar with the language introducing a one character typo during a character-by-character transcription from a book is evidence that "the syntax is confusing"?

What an odd yardstick to use.

The point is that the code is hard to understand. In this case it's a bracket misplaced, so the compiler will pick it up immediately, but if it's a misplaced +1 or index then you won't notice until you get hacked with a buffer overflow.

Now if you put each argument on it's own line, or use reasonable variable names - something that C programmers seem to fight against - neither of those bugs happen, because you can just look at the code and see the problem straight away.

Not only do I understand that code, and agree it's reasonable C code, I suspect you made a mistake when copying the memmove line. I think it should be:

  memmove(nvtab.nameval+i, nvtab.nameval+i+1,
          (nvtab.nval-(i+1)) * sizeof(Nameval));

Experience C programmers will know memmove - it's been a long time since I even saw the signature, but I thought it was going to be source, destination and size. (Looked it up just now to be sure.) These "inline transformations" are common on addresses in C.

I personally like braces around for loops, but things like Nameval being the struct type for a nameval variable is common C practice.

As emidln points out, your complaints seem to suggest unfamiliarity with C on your part rather than any flaws with that code, which looks perfectly fine to me. To his responses I'll only add:

> Confusing function explanation in a custom format.

It's a straightforward explanation in 6 words of English of what the function does. That's not a "custom format", that's a simple and concise introduction to the function. Far preferable to some mess of nonsense boilerplate XML.

Also worth mentioning is that in the context of the book that function sits in part of a larger discussion which, IIRC, gives the definition Nameval struct (that's definitely not some kind of accidental case flub), talks about the structure of nvtab, etc.

I'm absolutely shocked that someone can defend this code example. OK, you say it's readable for an experienced C programmer which I'm not. But is that really the best practice you want to teach other programmers? Fourfold inline computation? Cryptic variable names like nvtab.nval? No curly braces around a block where they are optional but prone to error if missing? Comments that use deep local jargon (what is nameval, what is nvtab)?

Defend it all you will (and also downvote just because you disagree, why thank you), I stand by what I said: The Practice of Programming is a harmful book and cannot be compared to Code Complete which is much more thoughtful and has unspeakably more attention to detail in naming, syntax, logic, programmer's psychology, project scope, everything.

> But is that really the best practice you want to teach other programmers?

Apart from using braces for `for` loops, yes.

> Fourfold inline computation?

This snippet

    void *dest = blah blah;
    void *src = blah blah;    
    size_t cnt = blah blah;
    memmove(dest, src, cnt);

isn't any different from memmove(blah blah, blah blah, blah blah) if you program in C. Introducing unnecessary noise doesn't contribute to code clarity.

> Cryptic variable names like nvtab.nval?

Suggest a better name. name_value_table.number_values? And give me one good reason how is this better?

There is a whole camp up in arms against abbreviating `count` as `cnt`. Though they never told me what issue they have understanding that `cnt` means `count`.

The only issues I have with abbreviations is they might introduce typos if you choose confusing ones. nval, nvtab etc aren't confusing, not by a mile. If you are confused by them, expanding them isn't going to help you either.

> Comments that use deep local jargon (what is nameval, what is nvtab)?

A localized code snippet uses local jargon. If you disagree, I would love to see your suggestions on improving them.

> Defend it all you will (and also downvote just because you disagree, why thank you), I stand by what I said:

Apart from standing by, show us how do you make it more readable. Your complains so far are fluffs.

> The Practice of Programming is a harmful book and cannot be compared to Code Complete which is much more thoughtful and has unspeakably more attention to detail in naming, syntax, logic, programmer's psychology, project scope, everything.

Sounds like Code Complete is programming for people who can't program.

I thought that CC was good when it came out, but it's gotten pretty long in the tooth. There needs to be a modern version.

> It's a pile of tautologies and common sense.

I was about to say the same exact thing, but was too afraid to because of the backlash.

That book has little to no use. It's a book you would give to someone that's a -1 level programmer on a 1 to 10 level scale, to bring him up to a 1. Really, it is.

I've always wondered if its recommended because people were not reading it, or if there is a case of general incompetence (the type that would get you fired, or not hired) in the general programming pool.

I read it when I was about a 1 on a 1-10 scale, and it probably helped bring me up to a two - which is a worthwhile ROI on a book.

I think that is why it is so recommended it is intended for people that are just entering into programming not individuals who have learned the common sense through experience as such it's value is very much dependent on where you are at in programming when you read it.

> My advice is to learn to use your favorite editor with a TAGS file, then go navigate through a large open source project, and extend it in some minor way. That's more profitable than enduring any book on "design".

If this were a book, it would probably go on the "Books Programmers Claim to Have Read" list.

Agreed on Code Complete. Never understood why people thought it was worth reading. Much better is Steve Maguire's Writing Solid Code.

Have to agree on Code Complete. The first edition was a load of waterfall bollocks and I couldn't believe anyone wrote code like that. It actively put me off a "proper" programming career. The second edition, apparently, reduced that shite, but by that point I wondered "if the author is just reproducing dogma, why bother?"

Code Complete was published in 1993, so I think it can be forgiven its emphasis on waterfall development. It back its advice by citing real studies of software project, though the projects were from the 1960/70s at big companies like IBM.

Like I said, its a book about dogma and cherry-picked studies. The dogma and studies were wrong. So if you want books about broken dogma and studies, read Code Complete.

Code Complete prepared me to learn that stuff through experience: http://lists.canonical.org/pipermail/kragen-tol/2007-March/0...

Thank you! I'm beginning to think all the Code Complete recommendations are a large scale troll-in-progress on the programming community. I found a copy years ago and opened it up to a random page right around the middle of the book. I was then greeted with a half-page or longer explanation of how the condition of a while loop is only evaluated once per iteration, rather than magically causing the loop to terminate the instant it becomes false. I was just flabbergasted. Again, this wasn't in chapter zero somewhere, but hundreds of pages into the book.