Clean Code

Cory Foy writes "As developers, system admins, and a variety of other roles in IT, we have to deal with code on a daily basis. Sometimes it's just one-off scripts we never have to see again. Sometimes we stare at something that, for the life of us, we can't understand how it came out of a human mind (or, as the book puts it, has a high WTF/minute count). But there is a time when you find code that is a joy to use, to read and to understand. Clean Code sets out to help developers write that third kind of code through a series of essay-type chapters on a variety of topics. But does it really help?" Read below to find out. Clean Code - A Handbook of Agile Software Craftsmanship author Robert C. Martin pages 431 publisher Prentice Hall rating 10 reviewer Cory Foy ISBN 978-0-13-235088-4 summary A great book for anyone wanting to really improve how they write code I had the pleasure of attending Bob Martin (Uncle Bob)'s sessions at several agile software conferences over the past several years. In them, Bob has a unique way of showing us the value of clean code. This book is no different. There is a warning in the introduction that this is going to be hard work — this isn't a "feel good" kind of book, but one where we slog through crappy code to understand how to make it better. The authors also point out that this is their view of what clean code is all about — and fully acknowledge that readers may "violently disagree" with some of the concepts.

The book wastes no time diving in covering "Meaningful Names", "Functions" and "Comments" right in the first several chapters. While I could sum up the chapters by saying, "Use them", "Keep them small" and "Comments don't make up for bad code" it wouldn't do the wisdom in the book justice. For example, in the meaningful names chapter, he talks about making pronounceable and searchable names — staying away from things like "genymdhms" (Generation date, year, month, day, hour, minute and second) and preferring things like MAX_STUDENTS_PER_CLASS.

After touching on formatting rules (including some very interesting graphs on the file and function length distributions in some common open source projects) he dives back into some more controversial topics — "Objects and Data Structures", and "Error Handling". The Objects chapter does a great job of drawing a line in the sand between Objects and Data Structures and why it really is both important, and clearer, to keep your privates in your private classes.

The Error Handling chapter is important because of the application of earlier chapters — the Do One Thing rule. Your functions should do one thing — either handle business logic, or exception handling, but not both. It's the difference between this:

try { s = new Socket(4000); s.OpenSocket(); string data = s.ReadFromSocket(); if(data == "32") data = "42"; printer.print(data); } catch(Exception ex) { if(ex == NetworkInterruptException) { //do something } if(ex == PrinterOnFireException) { //do something } logException(ex); }

And this

try { tryToPrintDataFromSocket(); } catch(Exception ex) { logException(ex); }

We then move on to "Boundaries" and "Unit Tests" — the critical points where we tend to really let code go. If we work hard, usually we can keep our own code clean. It's when we have to begin interacting with other systems that things start to go astray. In these chapters, Bob and James Grenning show us how to keep our code at the boundaries clean — and how to keep our code working, period. The authors are proponents of Test-Driven Development, and the chapter on unit tests is a fresh reminder that those tests are just as much code, and need to be kept just as clean as any other code we write.

We then begin to move at a higher level, starting with "Classes" and "Systems". The classes section should be familiar to most any OO programmer — keep the classes small, with a single responsibility, and low coupling. He also talks about Organizing for Change which is a great section on how to structure classes in a way that keeps them open to change. The Systems section continues along the path with the great reminder to "Separate Constructing a System from Using It". Here they go into Dependency Injection and Aspect-Oriented Programming, which I'll address in a bit.

Moving even higher up the chain, the book then tackles "Emergent Design". The key is to keep the design simple, which according to Kent Beck, means:

• Runs all the tests
• Contains no duplication
• Expresses the intent of the programmer
• Minimizes the number of classes and methods

With the above list given in order of importance. Really this breaks out to "Runs all the Tests" and "Refactoring" or making the code better. Simple design is perhaps one of the harder things out there, and yet the most important. When you look at systems that highly scale, it's because they are made up of simply designed components which work very well together.

After the Emergent Design chapter there is suddenly a chapter on Concurrency. This was not something I expected to see, but was very glad to. Too many times books about patterns and design don't address problems like scaling and concurrency. But this chapter does a great job of introducing the necessary steps that need to be taken to deal with concurrency — while still keeping your code clean. The book also provides an appendix which goes even deeper into the concurrency topic which I found to be quite good. Both this chapter and the appendix provide some very valuable rules that I personally have used when writing concurrent systems — like "Get your nonthreaded code working first" and "Run with more threads than processors" to flush out problems.

Chapters 14-16 cover the cleaning up of three different sections of code — an argument processor, JUnit and SerialDate, which is part of the org.jfree package. These chapters really hold true to the warning in the introduction that we'd be going through some code. However, the refinements work very well, and I think that each of them show the value of how much cleaning up the code can improve the readability of even code that works well and seems clean.

The last chapter is a "Smells and Heuristics" chapter which I'm finding to be a handy reference guide for code smells I see. When something is bothering me with code I'm reading, I flip to this section first to see if they have it listed. And with things like "Replace Magic Numbers with Named Constants" you can be sure that all of the advice that should have been beaten into your head long ago is still there, and relevant.

All in all I think this is a very valuable book for any developer wanting to improve how they write code. For senior level people, some things may seem trivial, but if you really take the time to look at the structural changes being made and apply them, you will write better code. For functional developers — the authors believe in OO, but there are still valuable nuggets that are applicable outside of that (like "Use Copies of Data" in the concurrency section). And for any developer, the insights are really good, and you'll find yourself writing down little snippets to hang on the wall.

The challenges with the book are first that it is just as they said — hard work. This is not a flip-through-with-your-mind-shut-off type book. If you want the most out of it, you have to be willing to really work at it. The other challenges are that at times it gets way too Java-centric. All of the code examples being in Java is fine, but some of the chapters (most notably the Systems chapter) really go heavy into Java tools and the Java way which, to me, weren't always applicable across languages.

All in all, I'd highly recommend this book to anyone wanting to improve how they write code. You likely will find yourself violently disagreeing with parts, but the total sum more than makes up for it.

You can purchase Clean Code - A Handbook of Agile Software Craftsmanship from amazon.com. Slashdot welcomes readers' book reviews — to see your own review here, read the book review guidelines, then visit the submission page.

Comments

I really want a copy of this...

[shellster_dude]

to set right next to my "How to Write Unmaintainable Code".

Re:I really want a copy of this...

[Horus107]

"How to Write Unmaintainable Code".

Use Perl!

Re:I really want a copy of this...

[antifoidulus]

You have Microsoft's Software Engineering methodologies printed out?

Re:I really want a copy of this...

[Anonymous Coward]

to set right next to my "How to Write Unmaintainable Code".

Perhaps you also want a copy of The American Spelling Book to sit next to the code books? Just helping out - so you don't get nitpicked next time you post.

Re:I really want a copy of this...

[Anonymous Coward]

Um, he used proper grammar. He is putting this book beside the other, therefore he is setting it next the other. Both books would be sitting on something.

Re:I really want a copy of this...

[StarfishOne]

A real programmer is lazy and uses a random character generator. ;p

Re:I really want a copy of this...

[Surt]

Mod parent redundant, gp already said 'Use Perl!'

Re:I really want a copy of this...

[bb5ch39t]

Pah! You want unmaintainable code? Use APL! Now that is a real programmer's language! A real sick programmer who likes Greek letters along with other make up symbols not in any other language on this planet.

Re:I really want a copy of this...

[Anonymous Coward]

Thankyou! I'm glad you figured-out what he was complaining about, I'd thought that somehow "unmaintainable" was another one of those words spelt differently by Americans than the rest of the English speaking world. Yet I couldn't find it spelt any other way.

Um, he used proper grammar. He is putting this book beside the other, therefore he is setting it next the other. Both books would be sitting on something.

Re:I really want a copy of this...

[MikeDirnt69]

"How to Write Unmaintainable Code".

Use Perl!

Plus GOTOs

Re:I really want a copy of this...

[Eudial]

to set right next to my "How to Write Unmaintainable Code".

It's an artform, some people make it look so easy, but to write truly horrible code takes lot of practice. The key is gotos and ifs (preferably nested deeply). Consider the first "clean" sum generator:

int sum(int n) {
    if(!n) return 0;
    return sum(n-1) + n;
}

We'll see about that:

int sum() { int n,ro,r; ro=-1; n=r=0;
f: if(n<10) {
    ro=r;
    r=r+n++;
    }
    if(!(ro^r)==0) goto f2;
    if(n>=10) goto f2;
    goto f;
f2:
    return r;
}

It's important to note just how unmaintainable this function is. It's hard coded (the limit is stored in two different places), so that it only calculates the sum of 1...10, (so, in fact, the entire function could be replaced by a a constant integer). It also has a redundant check, to make sure that the two are the same (so that it doesn't get too large), but it might get too small. Naturally, goto is cruise control for cool.

Re:I really want a copy of this...

[tjwhaynes]

Consider the first "clean" sum generator:

int sum(int n) { if(!n) return 0; return sum(n-1) + n; }

It's interesting you chose this one. I write a lot of Perl (tens of thousands of lines a year) and you might have done this in perl:

sub sum {
my $input = shift;
if ($input =< 0) return 0;
return sum($input - 1) + $input;
}

at which point you would tried it out on some large number and cried about the performance. Now the code is clean (albeit somewhat lacking in type checking) and it would be a shame to lose that cleanliness in the search for performance. This function is deterministic, so if we can cache the result, we can get the performance we want at the expense of memory usage. So we add the following to our code:

use Memoize;
memoize('sum');

and magically, we get caching on the sum subroutine. And our code remains clean and understandable.

Just because anyone can write unreadable, unmaintainable Perl doesn't mean you have to...

Cheers,
Toby Haynes

Re:I really want a copy of this...

[I cant believe its n]

Complaints about GOTO statement concidered harmful.

Re:I really want a copy of this...

[Eudial]

There are naturally various considerations: Value caching as you mention, whether the programming language optimizes tail recursion, and so forth.

But the real shenanigans in the function is that you can use mathematics and find that the sum of the series 1...n is n*(n+1)/2 straight away, so making such a function is a moot exercise altogether.

On the other hand, keeping that sort of mathematics arcane and shrouded in mystery creates thousands of extra programming jobs all across the world.

Re:I really want a copy of this...

[linhares]

Invention of term concidered considered harmful.

Re:I really want a copy of this...

[I cant believe its n]

"I confess my doubts. Thanks to the criticism of the comrades, I have been able to purify my language. I bow in humility to the opinion of my comrades and the Party and am thankful for the opportunity to correct my spelling. You enabled me to repudiate my deviational language. I acknowledge my debt to the selfless leader and the government of the people."

Re:I really want a copy of this...

[ChatHuant]

int sum(int n) {
if(!n) return 0;
return sum(n-1) + n;
}

Ouch... Your function fails miserably if n is negative. Check if n greater than 0, not !0

Re:I really want a copy of this...

[Thiez]

> int sum(int n) {
> if(!n) return 0;
> return sum(n-1) + n;
> }

Why do people insist on using recursion in stupid places?!

Do something like:

int sum(int n) {
    int result = 0;
    while(n > 0)
        result += n--;
    return result;
}

It's way faster since it doesn't have to go crazy with the stack. Also, it isn't harder to understand.

Somewhat related, one of my peeves is using recursion to calculate factorials. Grrrrr.

Re:I really want a copy of this...

[Follis]

The function is tail recursive (or could be if your language requires the sum+n to be n+sum). Hence most interpreters/languages will convert it to a jump. Recursion more closely embodies the Series representation of the sum.

Re:I really want a copy of this...

[Morty]

Y'all do realize that sum(n)==(n^2+n)/2, right? A solution that contains either recursion or a loop is inherently bad, with or without memoization. This is a O(1) problem. In Perl:

sub sum() {
    my $n=shift;
    return 0 if $n=0;
    return ($n**2+$n)/2;
}

Re:I really want a copy of this...

[Morty]

Er. /. killed my less-than. That should say:

sub sum() {
    my $n=shift;
    return 0 if $n<=0;
    return ($n**2+$n)/2;
}

Re:I really want a copy of this...

[Samah]

A better example of recursive programming would be factorials or the fibonacci sequence. They're the two most common examples shown in textbooks (in my experience, at least). It's something similar to this:

int fib(int n) {
if(n<=1)
return 1;
return fib(n-1)+fib(n-2);
}
int fact(int n) {
if(n<=1)
return 1;
return n * fact(n-1);
}

Re:I really want a copy of this...

[Thiez]

Once again someone proves that a little maths knowledge can have huge advantages.

Yay for making me feel stupid though :(

Re:I really want a copy of this...

[Anonymous Coward]

or if you really hate the people maintaining your code, use php for that extra stab-in-the-eye touch!

Re:I really want a copy of this...

[Anonymous Coward]

Is 4chan down, or are there a lot of 4channers who're also slashdotters? A couple months ago, I could count the 4chan references on /. on one hand, and now they're through the roof.

Yeah, fuck you, I'm talking about 4chan.

Re:I really want a copy of this...

[greg1104]

If you're operating in integers with a fixed range, computing n*(n+1)/2 might overflow in situations where computing the sum via a series of additions will not. You need to consider which of (n,n+1) is even, divide only that one by two, then multiply by the other odd term to get something that is both a fast computation and utilizes the full range of the integer size you're working with.

While the above might seem simply pedantic, consider the case where a program built using a naive sum approach that needed the full range was broken by replacing it with the multiplication-based approach. That sort of issue, where clever code is more fragile than the simple implementation, is one reason some programmers shy away from being too clever.

Re:I really want a copy of this...

[CDMA_Demo]

You haven't heard of kx then: http://kx.com/q/d/q1.htm

Re:I really want a copy of this...

[zunicron]

I say we exile you to lands far away.

Re:I really want a copy of this...

[Raenex]

Ken Iverson was a Real Man of Genius.

Re:I really want a copy of this...

[zunicron]

Don't you think this is clearer?

(define (fib n)
  (if (< n 2)
    1
    (+ (fib (- n 1)) (fib (- n 2)))
))

Re:I really want a copy of this...

[Anonymous Coward]

Clean code != reinventing the wheel. Mathematicians solved this problem long ago:

int sum(int n) { return n * (n + 1) / 2; }

Re:I really want a copy of this...

[Samah]

Heh I was waiting for someone to throw out some lisp... I learned that at Uni and hoped to never again use it. My poor parenthesis keys. :(

Re:I really want a copy of this...

[MadKeithV]

Correction: it's one reason why some programmers *should* shy away from being too clever, yet they don't.

Re:I really want a copy of this...

[dwarfsoft]

I remember my second foray into obfuscation. A simple little function ended up like this:

#include
#include
#include
#include
int main(int(c),char(*a[])) {(!a[1])?exit(1):(*a[1]==0)?exit(getch()):(*a[1]==32)? printf("%c",*(a[1]+1)):exit(main((int)((strcpy(a[0],++a[1])||-1)&(6)),a));exit(main((int)((strcpy(a[0],++a[1])||-1)&(-40)),a));}

I didn't know I had it in me... the first started out elegant.

l(char*O){return*O?1+l(++O):0;}

also, this one was fun to write up on the university board during our first C++ tutorial just to watch all the beginners heads explode. They dared to ask for a simple function ;).

I never went for obfuscation again after this, I learned my lesson.

Re:I really want a copy of this...

[Wendy Satan]

Ah. Somebody did see Perl and didn't understand it's beauty. Or saw some obfuscated code (which is code deliberately made hard to read, just for fun and often for beauty). But this certain somebody probably did not see the millions of wonderful programs written in Perl at companies that employ hundreds of thousands of people. Perl Success Stories. Perl community. Perl Best Practices. YAPC. Perl Monks. CPAN. Perl Workshops. Perl Mongers. All those people must be mistaken... Sigh...

Re:I really want a copy of this...

[Anonymous Coward]

FWIW, n * (n + 1) / 2 does not handle integer overflow correctly.

(n & 1) ? ((n + 1) / 2) * n : (n / 2) * (n + 1)

does.

Re:I really want a copy of this...

[Anonymous Coward]

I am surprised you did not get modded as a troll. I believe Microsoft does better than most of its competitors, otherwise they would not have the market that they still do.

Also, where is GNU Hurd again? Is it to be released in a coupled package with Duke Nukem Forever?

Thought so...

Re:I really want a copy of this...

[try_anything]

Make up symbols? How do I type the "lipstick"?

Re:I really want a copy of this...

[krappie]

I used to think perl was great. I used to think you could totally write maintainable code in perl. The thing is, you CAN! It's just that with a project with several people, it tends to not happen.

Re:I really want a copy of this...

[n7kv]

Or a SAP engineer?

Re:I really want a copy of this...

[GarrettZilla]

The really skilled use things like GOTO DEPENDING in COBOL, and a computed GOTO in Fortran.

I always preferred writing self-modifying machine code.

Re:I really want a copy of this...

[Eudial]

int sum(int n) {
    if(!n) return 0;
    return sum(n-1) + n;
}

Ouch... Your function fails miserably if n is negative. Check if n greater than 0, not !0

If the programmer feeds it stupid input, the function returns in kind.

That's the sort of tough love that's necessary to put hair on the budding programmer's chest.

Re:I really want a copy of this...

[Follis]

Yes, I do, but the argument was that the stack would explode, and I wasn't arguing that recursion is _efficient_

God's code...

[turtleAJ]

According to xkcd
http://xkcd.com/224/

Re:God's code...

[Anonymous Coward]

Damn you for posting this link! I've lost myself on xkcd for an hour (again)!

Re:God's code...

[SlowMovingTarget]

Best bit of the comic: "My God! It's full of cars!"

Put that together with Larry Walls oatmeal and finger nail clippings quote and you have Lisp in a Nutshell.

Good review

[raddan]

Wow, good review. I usually skip over the reviews, because I find that they're filled with inside jokes and wandering monologues, but in this case, the review was well-written, thoughtful, and the book seems interesting. I'll probably pick it up. If this was a Slashvertisement, well, it worked.

Re:Good review

[bennomatic]

Good meta-review. I usually skip... Ok, you get the joke.

Re:Good review

[Anml4ixoye]

Thanks. It was *not* a Slashvertisement - I try my best to actually make the Book Reviews I do meaningful. ;)

Re:Good review

[dubl-u]

Good meta-meta... I... joke.

Re:Good review

[Anonymous Coward]

Mod parent up, +1 Brevity.

Re:Good review

[Godji]

What, you mean that was a META-Slashvertisement?! I think my head just exploded...

Re:Good review

[Spy der Mann]

Good meta-meta... I... joke.

Good recursive [ERROR: STACK OVERFLOW]

Re:Good review

[Bill, Shooter of Bul]

No, it was a good review rather than a slashvertisement. I'm not buying it because you described it well enough for me to tell that it was not the book for me. Although that is the default state, It also means that I won't have to open the book myself, if I see it in a book store.

Not ragging on you in particular, but I've never bought a book reviewed on slashdot. They all seem to be geared towards the novice. Where is the book review for "advanced systems programing in Haskell"? Or "Algorithms for taking over Delaware" You know, books for nerds.

Re:Good review

[hardaker]

Does this mean you're going to buy the review?

Run with more threads than processors

[nwf]

Run with more threads than processors

Funny, I've found more problems by running with fewer threads than processors. Otherwise, you aren't necessarily getting true concurrency. Running ten threads on a single processor isn't going to help you find some of the pesky concurrency issues that arise from true parallel execution. Of course, one should run with more threads than processors to test that as well.

Either way, writing non-trivial parallel code isn't easy.

Re:Run with more threads than processors

[Anonymous Coward]

So you're saying that you generally find more concurrency issues by running less than one thread on a single processor?

Re:Run with more threads than processors

[Anonymous Coward]

It's amazing how much code there is that doesn't run as expected when you run it with fewer threads than processors.

Especially on a single-processor machine.

Re:Run with more threads than processors

[Anonymous Coward]

He is talking about the case where you have 1024 processors and 750 threads.

Re:Run with more threads than processors

[warhammerkid]

He's not saying that you should debug concurrency with more threads than processors. What he is saying is that you should first work out issues not related to concurrency in threaded code, and then fix the concurrency issues using whatever method you deem correct.

Re:Run with more threads than processors

[BitZtream]

The solution is to make sure your parallel code is trivial, so it can be dealt with in a sane matter. When you start firing off threads that handle complex tasks and interact with other complex tasks often, it becomes VERY hard to keep things sane.

Break complex tasks down into smaller, trivial ones that can be controlled easier and reduce the concurrancy/contention issues to very small easy to manage chunks.

Re:Run with more threads than processors

[Anonymous Coward]

LOL

Re:Run with more threads than processors

[Skrapion]

+1 Insightful? More like -1 Poor Reading Comprehension.

If you have a quad-core machine and you run your app with three threads, then you're almost guaranteed that all of your threads will be running at once. On the other hand, if you're running with five threads, and thread #5 conflicts with thread #3, you may never notice that, because thread #5 could be sleeping the whole time.

And as the GP said, it's a good idea to test your code with more and less treads than the optimal number.

Re:Run with more threads than processors

[Skrapion]

Let's look closer at what the OP wrote:

"Run with more threads than processors" to flush out problems.

So what you're saying is that you should run with more threads than processors, and you should do that to flush out problems, but the problems you should be trying to flush out with this technique should not be concurrency related?

I think you're misinterpreting the OP, because the best way to flush out non-concurrency-related problems would be to run in a single thread (or with no concurrency-related code at all if your framework supports that). That falls in the category of "fewer threads than processors". You may agree with the GP more than you realize >;)

Bravo!

[fferret]

Even if I was still coding, (moved on to sys/netadmin several years ago,) this book would deserve a huzzah! OK, now we've made it readable, when can we make it efficient, and get rid of all the bells&whistles that have turned software into bloatware!?

Re:Bravo!

[sakdoctor]

Is this really what passes for informative these days?

Re:Bravo!

[bugeaterr]

huzzah!

OK, for which Renaissance Festival are you sys/netadmin'ing for and is it hard to type whilst wearing plate mail and hoisting a flagon of mead?

Re:Bravo!

[Anonymous Coward]

Mod parent up!!

Re:Bravo!

[fferret]

Actually, I'm running a rack, wearing IPCHAINS. Can't afford plate.

Is the problem one of craft or mentality?

[The Clockwork Troll]

I don't know that this is the right book for the general problem.

In my career, the engineers who have been the most effective and most pleasant to work with usually do what they can to be better teammates. This includes but is not limited to: writing good code (or improving/refactoring existing code), and managing their personal interactions with teammates toward rational consensus and general embetterment (a perfectly cromulent word).

In my experience, the guys who consistently write the worst code also tend to have "lone wolf" mentalities. These are the guys who say, "if it was hard to write, it should be hard to read", and not half-jokingly. I honestly get the impression that growing up they might not have had the sorts of personal interactions that lead a person to be mindful of "playing nice with others". Coding serves a much more selfish end. This doesn't mean they are not "productive" in the absolute sense, but they are solo silo stars and it's hard to pair or team them.

Put another way, the kind of engineer that would actually benefit from a book like this, has probably already read a book like this.

The needed book I think is for the manager: psychology of the antisocial geek

Re:Is the problem one of craft or mentality?

[Krishnoid]

but they are solo silo stars and it's hard to pair or team them.

Not that hard, depending on how you do it. You really find out who can work well with a partner if you do it right.

Re:Is the problem one of craft or mentality?

[dubl-u]

Put another way, the kind of engineer that would actually benefit from a book like this, has probably already read a book like this.

I think you've created a false dichotomy.

I haven't read this book yet (although Bob Martin's other stuff is great), but back at the dawn of time, I was working with a team that was all relatively young. When McConnell's "Code Complete" came out, we all went through it pretty excitedly.

Although we had the right spirit, and we each could have named some of the things in the book, none of us could have articulated all of them. And there were a lot of subtleties that we had never thought of.

So I'd agree that jerks won't read this and nice graybeards don't need to, there are plenty of people who are perfectly nice that haven't perfected their craft yet. They can use this book.

Re:Is the problem one of craft or mentality?

[Soko]

The needed book I think is for the manager: psychology of the antisocial geek

For the love of $DEITY, do not listen to ESR.

That being said, most geeks aren't truly anti-social - they just work differently. Being cut from a different cloth means that you can't always tailor them to your needs - you may have to modify your pattern a tad.

I've seen where giving an uber-hacker an inexperienced but - and this is key - very bright geek to teach brought them out of their shell a bit. Mostly because he n00b was able to not only learn the methods in coding, but how to properly speak to the geek and have them communicate.

Even then, don't expect them to always fit in a team or be able to communicate exactly what they're thinking. The latter is usually due to bandwidth limitations - hard to explain 500 ideas all at the same time without frustrating the person they're communication with.

Re:Is the problem one of craft or mentality?

[MadKeithV]

I had a related thought yesterday after re-reading parts of "The Pragmatic Programmer".
The first time you read great books like that, they are full of some real gems and a lot of items where you think "well duh, that's obvious".
Several years later, I notice that many of the things I thought were gems of wisdom were obvious to some of my colleagues, and some of my "duh"'s take hours to explain to them.

Re:Is the problem one of craft or mentality?

[darkwhite]

In my experience, the guys who consistently write the worst code also tend to have "lone wolf" mentalities.

In my experience, the people who consistently write the worst code are the people who have never been forced to reuse it.

All the good coders I know write most of their code the "good" way not because someone else might have to change it (although eventually that does come into play), but because they will. On the other hand, people who have literally not learned to reuse their code yet write unusable code.

yay!

[thhamm]

high WTF/minute count

hot damn. a new and useful [SI] unit. thanks /.

Re:yay!

[jbeaupre]

Minutes are well defined by a standard, but we still need to think of an easily measurable and reproducible WTF. For instance, waking up some place you don't recognize after drinking 10 shots of tequila the night before. Nope, still too much potential variability. How about pouring 1 liter of water at 0C onto a sleeping person's face? Hmmm. There's got to be something better.

Re:yay!

[Nerdfest]

Reference diagram:

wtfs-per-minute

Re:yay!

[myvirtualid]

high WTF/minute count

hot damn. a new and useful [SI] unit. thanks

All kidding aside, WTF/minute is a deceptive metric.

I remember poring over about 30 lines of C for about two plus days with a WTF/minute ratio in the hundreds or thousands. And I knew what the code was supposed to do! It wasn't that I didn't understand it, I didn't understand why the guy who wrote it, a brilliant, brilliant hacker, wrote it the way he did.

Over two days of following the nested ifs, the gotos (no STL, no exception handling, the gotos made perfect sense), the logic, then BAM!

"Wow, that's fast!"

It was the most difficult-to-read code I'd ever read - and it was brilliantly brilliantly fast. (It was a network proxy involving PKI-related messages embedded in LDAP, all based on ASN.1 - all speed improvements were important, his were amazing.)

Most of the time, high WTF/minute is a good indication that the coder should never, ever have been allowed near a keyboard. Live an awful lot of Java.

But every now and again, high WTF/minute is a sign of absolute genius. Like a lot of really cool Haskell code. Or wicked perl.

Hmm, perhaps it's not WTF/minute that we need to consider, but its first order derivative. WTF/minute that peaks then declines to zero suggests genius. WTF/minute that remains constant suggests a bad day or a lot of PHB pressure. WTF/minute that increases without bound suggests brain-damage and a potential career in sales.

Re:yay!

[dubl-u]

But every now and again, high WTF/minute is a sign of absolute genius. Like a lot of really cool Haskell code. Or wicked perl.

I think that depends on why you're coding. If you're writing code in the spirit that people write poetry, that's fab. Or if you're dealing with a performance-critical section that can't work any other way, then sure, that's fine.

But for most code (and more and more all the time), maintenance cost vastly overwhelms other factors. Real geniuses get the job done in a way that will last over the long haul.

Re:yay!

[Vizzoor]

Why not take advantage of all that the internet has given us? 1 WTF = the mental pain proportional to a man spreading his anus a certain distance.

Re:yay!

[Surt]

And if he had documented his code, explaining the performance advantages, you'd have read it in an hour and reached the same goal, and he wouldn't have dozens of WTFs to his credit.

Re:yay!

[sootman]

SI units always use seconds. :-)

Re:yay!

[MikkoApo]

I think the original metric is based on the sign of the WTFs. Positive WTFs are rare and usually the metric goes below zero, sometimes way below ;-)

Kidding aside, I'm just reading the book (chapter 2 - Meaningful Names) and from what I've read so far, the book seems really good and useful. In the beginning the author states that some of the guidelines might not work for everyone but at least the author gives a lot of food for thought.

Re:yay!

[Spy der Mann]

Over two days of following the nested ifs, the gotos (no STL, no exception handling, the gotos made perfect sense), the logic, then BAM!

"Wow, that's fast!"

And your understanding could've been faster if the author had bothered to include a comment block before the series of ifs/gotos.

Example:
/** The following series of if's/gotos are a hardwired implementation of
  * a finite state machine, as documented in the book "Efficient State Machine
  * examples for data processing (ISBN blablablabla, p.15).
  * The machine is as follows:
  *
  * A -> (condition 1) -> B
  * A -> (condition 2) -> C
  * ...
  *
  * The if at point 1 is node A
  * The if at point 2 is node B... etc
  */

// Point A of the FSM
    if(...) {
        goto B;
    }

True, comments aren't an excuse for bad code, and WTF/min aren't necessarily accurate. But difficult to understand code without proper in-code documentation is a potential disaster. In fact, I'd call your example a mega-WTF for its lack of comments.

Re:yay!

[camperdave]

I remember pouring over a few uncommented lines of WANG BASIC trying to figure out what was going on. The guy was doing something like 31.13-18.81 and using that to validate a date. It did not make sense to me. 31.13-18.81=12.32, yet this guy was using the third to sixth digit after the decimal point in his validation. I poured over the code on paper for days. Finally, I got access to the computer and typed in PRINT 31.13-18.81 and pressed enter. The result: 12.319999

Re:yay!

[Annymouse Cowherd]

You had to wait one centisecond before posting that short reply, right?

Re:yay!

[Annymouse Cowherd]

err not centisecond, decasecond.

Re:yay!

[CapitanMutanda]

It was a network proxy involving PKI-related messages embedded in LDAP, all based on ASN.1

a PKI based SSO solution? Maybe the architecture was as clear as the code that was badly documented. Certainly didn't need speed requirements as handling 3G GPRS that is easily done in Erlang (interpreted) in Ericsson SGSNs

Re:yay!

[AmberBlackCat]

I'm sure the ISO can come up with a standard WTF. It's just that the definition will be so vague that every time we try to implement it, we'll say WTF? And then we'll have our implementation. Pure genius.

Re:yay!

[myvirtualid]

a PKI based SSO solution... 3G GPRS... Erlang...

Not only was it not an SSO solution, it predated Erlang's open-source release by several years and pre-commercial 3G by several more. It was based on a rather bizarre architectural decision that can be interpreted as sensible back in the days when:

• There was still a lot of 16 bit Windows running around (amok?). Remember that? One of the main reasons "L"DAP exists, after all: If we were to create X.500 today, we might all be using DAP, since we'd not notice how heavyweight all of that ASN.1 processing is - after all, we can run Gnome and OO.o successfully! :-> (Hey, I'm running Gnome and OO.o on a 700 Mhz PIII - I'm kind of cheap - that blows the doors off any Intel-based computer I had at my disposal when I was reading that code... ...which is why I did most of my work under SunOS).
• We all thought opening connections was slow and expensive, so we did it rarely: Open a connection, keep it open forever. Funnily enough, we moved to the more modern - but still far from common wisdom (SSL wasn't quite invented, though it would happen soon enough, HTTP was still 1.0, most servers still did one accept() then forked for every incoming connection) - open-request-response-close model in fairly short order 'cause of a performance bottleneck in the server that translated LDAP to DAP and made the connection to the directory (and that extracted PKI messages and sent those to the CA).

Doing it again just a few years closer to the bubble-burst, a) that code would never have existed, since the need to embed PKI messages in LDAP had disappeared, and b) zippy performance could have been sacrificed for more maintainable code, since all of the boxes and OSes were so much faster to begin with.

As for comments or other documentation, well, it's been my experience that good coders who can write well are rare, and brilliant hackers who can write at all well are very rare indeed. There's a reason literate programming is confined to a relatively small community: Most of us just aren't wired that way.

Me? Great writer (/. posts aside :->), adequate coder. Most of my code is, er, was, fabulously well commented and bullet-proofed in the extreme, but slowly produced and pedestrian in function.

Guess that's why I became a system architect, then a PHB, and eventually a consultant!

Well, that and the layoffs. Yay, bubble.

Re:yay!

[Junior J. Junior III]

I propose that this new unit be named the Gates-Seinfeld.

Re:yay!

[Anonymous Coward]

nothing beats the effect of dropping a litter of water as an ice cube on someones sleeping face... talk about surprise..

Re:yay!

[John Hasler]

But we already have DIS29500.

Re:yay!

[Anonymous Coward]

nothing beats the effect of dropping a litter of water as an ice cube on someones sleeping face... talk about surprise..

OK Dude - euwwwwwww!

Re:yay!

[Anonymous Coward]

Why create "difficult to understand code?" It's not warranted in 99% of most systems.

Why do people who like to defend comments insist on their being everywhere, when the vast majority of could should not need them?

Why do people always argue the edge cases?

Why should we have to suffer through buttloads of poorly written, out of date, inaccurate, and otherwise misleading and distracting comments, in order to explain a tiny fraction of a system?

This should come naturally but...

[prayag]

Its a pity us computer science / programming students are not taught writing clean code in classrooms. Clean is simple and intuitive. Its just what generic programming books illustrate and teachers condone. I really hate it when teachers do not take care of a students code quality/ cleanliness / and design as long as it works and has plenty of comments.

By the time we graduate writing unclean code becomes a habit. Something which could be checked at the very starting becomes a huge enough problem to require professional books.

Re:This should come naturally but...

[Ethanol-fueled]

"Clean" in the newbie/classroom sense is subjective. Do you mean clean as in compact, or clean as in readable? What's good for the student is often not what's good to a style-nazi instructor. For example:

public static List getShortestPathTo(Vertex target) {
List path=new ArrayList();
for(Vertex vertex=target; vertex!=null; vertex=vertex.previous)
path.add(vertex);
Collections.reverse(path);
return path;
}

Vs.

public static List getShortestPathTo(Vertex target)
{
List path = new ArrayList();

for (Vertex vertex = target; vertex != null; vertex = vertex.previous)
path.add(vertex);

Collections.reverse(path);
return path;
}

I know, looks like crap because of /.'s gimpy text parser.

Re:This should come naturally but...

[halsver]

If your TA (who is the one most likely to grade your code) ever talks to you, I would hope he or she mentions how readable your code is.

That said, I have met some very anti-social CS TAs, but they would express their dislike for unreadable code with low marks.

Re:This should come naturally but...

[PainKilleR-CE]

It should be noted, though, that many students have been through classes in which their code was not reviewed if it compiled and passed the tests required by the assignment.

This is especially true of larger projects done for class, as even the TA has something better to do than review the poorly-written code of 60 CS students in a first-year class.

Re:This should come naturally but...

[mikael]

What one programmer's definition of documented, is another programmer's definition of over-documented. Should the documentation for a function be at the top of the file, above the function definition, or between the function definition and the first opening brace?

Should comments be alongside the lines of code they are describing, above them at the start of the line, or are they simply index points numbers (eg. // 1.1) with the actual definition above the function?

Re:This should come naturally but...

[try_anything]

Who in a classroom can teach students to write clean code? Being taught by a typical TA is the equivalent of being taught by a guy with less than one year of industry experience. When it comes to coding style, they should be learning, not teaching. Most professors aren't any better.

I'm not sure it can be taught anyway. Just like writing in a natural language, you learn what good and bad code is by reading it, especially your own.

baby names

[Eternal Annoyance]

They provide a really good source of variable names. After that you could use town names... you're bound not to run out of variable names that way.

Does the book mention Linux desktops?

[Anonymous Coward]

...because there is no cleaner code than code for Linux desktops.

Bob's your uncle?

[192939495969798999]

"Bob Martin (Uncle Bob)'s"

No wonder he's so good at making clean code... Bob actually is this guy's uncle!

Depends on function

[BountyX]

Preformance related code and highly efficent code is the opposite of clean code. Clean code is often high level in nature, while efficient and robust code is low level and not pretty. Comments are for readabilty, not the code. Always go for efficiency.

Re:Depends on function

[Louis Kleiman]

So, you can't write code that is both pretty and efficient? Don't saddle the rest of us with your problems. "Clean code" and "Preformance related code" [sic] are NOT opposites. In fact, I have seen a huge number of situations where I sped something up by cleaning out the code.

Re:Depends on function

[leenks]

It depends on the situation.

Efficiency isn't always the desirable outcome as most code doesn't need to be exceptionally efficient - a good developer's time is expensive, and often anything that makes it easier to maintain is a good thing.

It also means developers can spend more time developing extra functionality rather than coding uber efficient code that usually isn't needed - and then rewrite poorly performing code.

That said, sometimes you really do want to go for the efficiency - a good developer will know when to do that and document appropriately (both inside the code and out - the last thing you want when planning a large change is to not know what is involved until you get neck deep in code).

Re:Depends on function

[Nerdfest]

It's taken me a long time to get myself out of this mindset. I used to always go for the absolute fastest implementation I could come up with. I now generally go with 'fast enough' rather than 'as fast as possible' if the latter is more maintainable. Sometimes the bar for 'fast enough' lowers, but not often.

Re:Depends on function

[dubl-u]

related code" [sic] are NOT opposites. In fact, I have seen a huge number of situations where I sped something up by cleaning out the code.

I know what you mean, but the guy has a point. I have also often sped things up by removing "performance improvements" that some dolt had added because he thought he was being clever.

My view, which I guess you'd agree with, is that it's best to start with clean, simple code. Usually, that's plenty fast. If performance tests prove that you have a problem, and a profiler shows you the source of the problem, only then should you sacrifice clarity for speed. And you should only do just enough to meet your performance goals.

Re:Depends on function

[Zet]

This is dead wrong. It's true that sometimes
purity is sacrificed for performance. But in
general, good clean code matches a good clean
design, which emerges when a problem is
well-understood. Even code that has been
tweaked to exploit certain compiler anomalies
can remain clean.

Re:Depends on function

[Frequency Domain]

Comments are for readabilty, not the code. Always go for efficiency.

I endorse the saying "when debugging, ignore the comments - they can be very misleading." Hence I want the code itself to be readable more than I want it to be maximally efficient.

Re:Depends on function

[Anonymous Coward]

Bzzt, fail, please go buy the book.

http://en.wikipedia.org/wiki/Optimization_(computer_science)#Quotes

Clean code is efficient and performs well because you can easily see where the issues are and optimise there appropriately.

Re:Depends on function

[Anonymous Coward]

You're joking I hope.

Clean is NOT the opposite of efficient.

>Comments are for readabilty, not the code

No. NO. NO!

There is no excuse for writing unreadable code. The code itself must be readable. Then comments are necessary to supplement the code, to help understanding the tricky parts, explain the reasons that lead to choose this or that method to solve a problem or -the most important- explain the INTENT of the code. How many projects (FLOSS and closed source) have I seen that were a mess because they don't bother with those simple and basic principles... Sad.

Re:Depends on function

[BountyX]

To all who disagree: please note my title. I agree with all of you that it DEPENDS on the implementation (hence my title). A good developer knows how to balance it out.
Clean code can be high performing, but most of the time, high performing code is not clean. Look at encryption algorithms. Look at Qt's premoc compiler. The nature of performance in code is inherently low-level. Want to maximize a function in C++ to its fullest extent? Great, take it too far and you end up with parts using inline ASM. Most preformance related code makes use of multiple calls in a single function to ensure that the scope usage is as short as possible. I wouldn't call 20 functions in one line of code readable. How do most people make it readable? Separate function return values into variables causing the variable to live in the entirety of its parentâ(TM)s scope. So you end up with less memory optimization. I guess when I think of performance related code, I think more of code optimizations (i.e. const int &var) that end up making a single line of code more complex and hence, less readable. I wanted to imply that many code optimizations result in less readable code due to the low-level nature and extra modifiers required to optimize code.

Re:Depends on function

[jgrahn]

Preformance related code and highly efficent code is the opposite of clean code. Clean code is often high level in nature, while efficient and robust code is low level and not pretty.

Clean code is the enemy of robust code? I've never heard anyone state that before.

Comments are for readabilty, not the code. Always go for efficiency.

Even when I don't need it? You don't make sense.

Re:Depends on function

[PainKilleR-CE]

Besides, you don't need as many comments if your code is easy to read. Reserve comments for making your intentions clear (so people can make sure the code works as intended), and explaining hacks and work-arounds when things don't work the way they should. Even my first year CS teacher told us not to use the alphabet as the source of our variable names, and most of us still had to learn the hard way.

Re:Depends on function

[Anonymous Coward]

Efficiency for efficiency's sake is inefficient.

Efficiency is hard work and the more work done on trivialities, the less time will be available for the critical stuff.

As for the idea that efficient code must be nasty, I'd say quite the opposite and hold up as an example the Amiga Exec by Carl J. Sassenrath. Unlike most of today's commercial OS's, the Exec was a true real-time kernel, but the nucleus consisted of a small core of very tight, clean general-purpose code that could be easily augmented by special-case functions as needed.

Re:Depends on function

[Nerdfest]

My apologies ... looking back at my post, I think a little refactoring is in order.

Re:Depends on function

[soshimo]

"We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil." (Knuth, Donald. Structured Programming with go to Statements, ACM Journal Computing Surveys, Vol 6, No. 4, Dec. 1974. p.268.)

Re:Depends on function

[soshimo]

Low level code can also be efficient and "pretty". The language used does not necessarily indicate how clean the code is. I've seen assembler code that made me want to cry it was so well organized. That code was also very easy to maintain. For any organization that plans on sticking around for awhile it's important that their code is as maintainable as possible. We all know that turn over rate for engineers is fairly high and it's not unheard of for programmers to have had 10 or more jobs throughout their careers (even more if they are a consultant). That being said, in order for an organization to protect it's IP, crown jewels, or what have you, it's imperative that the code can be picked up easily by fresh, new talent, otherwise the organization may end up hostage to the developers.

Re:Depends on function

[Estanislao Mart�nez]

My view, which I guess you'd agree with, is that it's best to start with clean, simple code. Usually, that's plenty fast. If performance tests prove that you have a problem, and a profiler shows you the source of the problem, only then should you sacrifice clarity for speed. And you should only do just enough to meet your performance goals.

While this is overall not bad advice, it's still not quite right, IMHO. The problem is that you're equating "simple" with "clean" and "unclear" with "fast." This association is wrong. There are many cases where you have the choice between a simple but slow solution to a problem, and a complex but faster one, and you should pick the complex one when performance is critical. But the key thing here is that you should still write the complex solution clearly. The complex solution should be harder to understand because it's trying to do something more complex, and the code should still be written to help the reader understand what is happening. Very often, it suffices to put a medium-sized comment before the tricky code, with an informal description of the algorithm.

Re:Depends on function

[Raenex]

Your post is incomprehensible. You say "it depends" and then you say "always go for efficiency". They just aren't compatible.

Efficiency is not worth sacrificing code readability unless there's a demonstrable need for it. You have your priorities backwards. First priority is to get your code working in a straightforward manner. Give some thought to performance up front, but don't obfuscate your code for performance reasons unless you really need to.

Re:Depends on function

[try_anything]

Clean code can be high performing, but most of the time, high performing code is not clean. Look at encryption algorithms. Look at Qt's premoc compiler. The nature of performance in code is inherently low-level.

Quite the opposite. High-level factors determine performance to within a scaling factor. Only after you get the high-level structure right does it make sense to optimize at lower levels, and then you can usually limit the optimizations to a few hot spots in the code. (There are well-known exceptions to the rule that most of your execution time is spent in a small minority of code, and compilers are usually exceptions, so your point about premoc stands, but most code isn't like that.)

Most preformance related code makes use of multiple calls in a single function to ensure that the scope usage is as short as possible. I wouldn't call 20 functions in one line of code readable. How do most people make it readable? Separate function return values into variables causing the variable to live in the entirety of its parentÃ(TM)s scope.

I'm not sure exactly what you're talking about, but any decent compiler will happily reuse registers containing data that will not be used again, regardless of whether the objects are in scope are not. You only have to worry about scope if the objects have nontrivial destructors.

Also, you don't have to use a function or a single line to create a scope; you can use curly braces. You can't have written much C++ code without knowing that, because that's often the only readable way to be precise about RAII resource scopes. It sounds like you're getting way too fancy for your own good and writing "optimized" code in a language you don't understand.

Re:Depends on function

[GooberToo]

Clean code is the enemy of robust code? I've never heard anyone state that before.

He doesn't know what he's saying. Clean code normally means robust code but may not be performant code. Just the same, they need not be mutually exclusive.

Of course...

[viljun]

... we all write clean code. Let's buy this book to our fellow workers.

Clean code?

[Mycroft_514]

Just write the code like it is YOU that has to debug it at 4am. Nothing to see here, move along, move along.

Re:Clean code?

[Anonymous Coward]

Just write the code so that it is ONLY you that can debug it at 4am.

Fixed that for you. And yes...I'm a consultant. :-)

Re:Clean code?

[neuromanc3r]

Bad idea. If I know that I will have to debug it, I can use whatever variable names I want. Which is not necessarily what makes sense to other people.

Re:Clean code?

[Mycroft_514]

LIKE it has to be you - not that it will. If I write code like that, then my buddy can debug it at 4am and not have to call me to fix it. And if his code is like that, I can figure out what is wrong easily and not have to spend hours fixing it.

Re:Clean code?

[fyoder]

Just write the code like it is YOU that has to debug it at 4am.

It's likely it will be me who has to debug it at 4 am. Writing clear code with helpful comments where necessary makes me appreciate my past self, since if the code is more than a few weeks old, I've already forgotten a whole lot. If it's more than a year old, it might as well have been written by someone else. This is, in fact, how I learned the value of clear coding. It wasn't for others, but for myself. The early shit I wrote in perl looks like something that might originally have been scrawled in feces on the padded cell of someone totally deranged.

Re:Clean code?

[tirerim]

Yeah, that's not going to help when I'm debugging it two years later and have no clue what I was thinking when I wrote it. I have seriously gone in to look for a bug, said to myself, "What idiot wrote this incomprehensible garbage?", and looked at the cvs log only to discover that the idiot was me.

Re:Clean code?

[LearnToSpell]

As Damian Conway writes in Perl Best Practices (much like this book, it seems),

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.

Re:Clean code?

[Anonymous Coward]

The problem is, at 4AM, the code is still fresh in your mind, and you won't give a damn.

Even if the code is 4 years old since you last looked at it, enough of an inkling of context remains in your head to reconstruct the entirety of the context of the program.

Instead, programmers should contribute in "code shares." As you write code, you invest a portion of your paycheck in that code. As the codebase matures, the value of your code shares will increase as the code becomes more valuable. However, the value of your shares obviously declines as the number of lines of code you've written gets removed. Ergo, it is strongly in your financial best interest to write damn good code, that doesn't need replacing.

Re:Clean code?

[Anonymous Coward]

Well geez, if I'm gonna go to that much trouble I might as well just not put any bugs in it in the first place!

Re:Clean code?

[pilybaby]

No, you should code as if the person that is debugging your code at 4am is an axe wielding maniac who knows where you live.

Re:Clean code?

[Anonymous Coward]

As Damian Conway writes in Perl Best Practices (much like this book, it seems),

Always code as if you are a violent psychopath.

There fixed that for you.

The Elements of Programming Style

[steveha]

I will seek out Clean Code and take a look at it. But I'd like to take this opportunity to plug a classic favorite of mine.

The Elements of Programming Style by Kernighan and Plauger is an old book... so old that all its examples are in either Fortran or PL/I. It doesn't matter. They take examples of code, ruthlessly dissect each one, then rewrite each one; and in every case, their rewritten version is hugely improved. Then they present a rule that encapsulates what they did to improve the example. Their writing is clear, insightful, and entertaining. This is a book that I pull out again and again and re-read.

http://www.amazon.com/Elements-Programming-Style-Brian-Kernighan/dp/0070342075/ref=sr_1_2?ie=UTF8&s=books&qid=1222277636&sr=1-2

steveha

Re:The Elements of Programming Style

[JohnReid]

I agree, this book is small but sends the right message. Should be required reading for anyone involved in programming of any sort. It starts off with a small Fortran program that is efficient but entirely cryptic. The cleaned up version makes it self explanatory and loses nothing in efficiency, especially with modern compilers. I'll probably get this "Clean Code" book also, but I'll never part with my "The Elements Of Programming Style"

So Dijkstra is no longer the go-to guy on this?

[ivandavidoff]

But seriously: I've always thought that coding Can be poetry

Re:So Dijkstra is no longer the go-to guy on this?

[pilybaby]

The First Poem Written for Computers

FTFL:

Waka waka bang splat tick tick hash,
Caret quote back-tick dollar dollar dash,
Bang splat equal at dollar under-score,
Percent splat waka waka tilde number four,
Ampersand bracket bracket dot dot slash,
Vertical-bar curly-bracket comma comma CRASH

If you think THAT's clean code

[bugeaterr]

You should see the SOAP request I wrote last year!
[rim shot]
Good night! Don't forget to tip your waiters!

Re:If you think THAT's clean code

[Anonymous Coward]

When code compiles and runs it is crucial to soak it. This way the code will gradually clean itself while you go to the pub.

Clean Code

[codepunk]

I recently ran across a situation where I looked a piece of code someone else wrote and thought to myself that
is really ugly. I set out to write a clean version but gave up when I figured out that no matter what I did
this was still going to be ugly. Not so much because of a poor job coding it but because of what the code had
to actually perform.....I guess it is just not possible to always put lipstick on the pig.

Re:Clean Code

[dubl-u]

I think a better way to look at this is that at the time you couldn't think of a better way. Often I've come back to a problem later and found some better abstraction. Or asked a colleague who has a nice trick to sort things out.

On some days, I think the the main job of a programmer is to hide the ugliness as well as possible. The code bases that really scare me are the ones where people have admitted defeat and let the ugliness seep everywhere.

Re:Clean Code

[codepunk]

Actually there are off the shelf products that could handle the situation easily, cleaner and much more robust. However
we where told to not spend any time on it since it is getting replaced. We all know how that story goes, that same line has been
used for the last 6-8 years and there is still no replacement in site....the ugliness lives on...

Re:Clean Code

[mdf356]

Last week I rewrote some code that had been annoying me since early 2003. I knew intuitively it could be done better at the time but I didn't have time (or, I think, skills at the time) to dig into it. After 5+ years of the code working okay but bugging me every time I came across it again, having hacks added on top, and constant improvement of the stuff around it (including a lot of deleting) I finally had my a-ha moment.

32 modified files and thousands of lines of code later, it was done, and my team rejoiced. :-)

Sometimes certain sections of code can't really be fixed until the stuff around it is improved first, because it all ties together.

Re:Clean Code

[Moochman]

This may be the case, but what you *can* do is make sure that all of the publicly exposed methods are at least easy to use.

Thing is, every class written is in a way an API unto itself. So even if it's ugly inside, make sure it's easy to use outside.

Re:Clean Code

[russotto]

Exactly. Code's often dirty because the problem is dirty. Either it's a collection of special cases which can't be generalized further, or there's a lot of error conditions causing the same effect.

Is it professional to cheat your boss?

[Corporate Gadfly]

Here's an interview with Robert Martin (part of a panel) where he talks about cheating the boss (by writing good code without permission to use the time).

Re:Is it professional to cheat your boss?

[dubl-u]

I totally agree with Bob Martin here.

Suppose I go into the doctor and say, "I'm tired and not getting enough done. Please give me a bucket of amphetamines." The doctor will say no, as that would be likely to cause harm, followed by death. Instead, they'll try to figure out what's really going on, and help me appropriately. That's what professionals do.

If a boss comes to me and tells me that for the new banking software they'd like me to skip testing, exception handling, and error logging, I'll say no. Instead, I'll ask them what their real goal is, and suggest ways they can achieve that.

Over and over I see developers offering to write unmaintainable garbage, only to get in hot water in a year's time because productivity is in the toilet. It's not even fun the first time, but people keep on doing it. They should stop.

Re:Is it professional to cheat your boss?

[Anonymous Coward]

Yes yes and yes. I totally agree.

Software developers are manipulated too easy by the managers. Maybe it is because we know we can always get a new job if this project goes down the toilet.

Re:Is it professional to cheat your boss?

[Anonymous Coward]

Great interview. You can tell that the panel are really experienced and that they have seen it all.

Re:Is it professional to cheat your boss?

[tieTYT]

Over and over I see developers offering to write unmaintainable garbage, only to get in hot water in a year's time because productivity is in the toilet. It's not even fun the first time, but people keep on doing it. They should stop.

But, as was said in that interview, the problem is convincing the "Developer Managers". You end up competing with people who use the Bait and Switch technique: They claim they can produce code faster and cheaper than you, but really, it's unmaintainable. We need to convince our managers that by saying no, we're doing them a favor.

Answer: definetely no!

[ThiagoHP]

So Dijkstra is no longer the go-to guy on this

Dijkstra would never ever be the goto guy because Goto Considered Harmful.

Re:Answer: definetely no!

[ivandavidoff]

Dude, I know. That's why it's funny to call him the "go-to guy".
*sigh*

Re:Answer: definetely no!

[ThiagoHP]

The subtler the humor, the better. Kudos to you. :)

Re:Answer: definetely no!

[maxume]

Cookie Monster.

who wants

[nawcom]

a perfect example of unclean code? http://thepiratebay.org/torrent/3497574/Windows_2000_source_code

Re:who wants

[Spy der Mann]

a perfect example of unclean code? http://thepiratebay.org/torrent/3497574/Windows_2000_source_code

Sheets of unclean code as toilet paper. A match made in heaven.

Re:who wants

[Anonymous Coward]

I call bullshit! Did you ever read this windows 2k leaked source code? Most of the code there (specially the kernel parts) is very well written. Actually, compared to any Linux kernel code, the windows code is poetry. And thinking about that, most of the code there was written around 1989, when there were no conventions nor "clean code" books.

You had me right up to "Agile."

[mellon]

For some reason, whenever I see that word in reference to programming, I want to run screaming in the opposite direction. Does that make me a bad person?

Re:You had me right up to "Agile."

[mustafap]

If it does, there are a lot of us bad people around.

Re:You had me right up to "Agile."

[Tassach]

No, it's natural to fear the (mis)application of the buzzword du jure. Agile has some good ideas, but like any other development methodology, too many people just blindly follow the formula without really understanding WHY it works or realizing that software development isn't a cookie-cutter process. Any methodology like Agile, or CMM, or whatever, is just a way of keeping the code monkeys in their cages grinding out code. There's only one way to write great code: hire great programmers. Management types love to believe that a swarm of code monkeys can produce on the same level as a brilliant top-tier programmer. They can't.

Re:You had me right up to "Agile."

[Anonymous Coward]

What is "Buzzword du jure": a catchphrase used by a judge?

I think you meant 'Buzzword du jour'

Re:You had me right up to "Agile."

[Enter the Shoggoth]

Abso-freakin-lutely! Agile isn't such a bad idea in principle but you tend to find that people who rave-on about it seem to think it somehow relieves you of the burden of creating project plans, software specifications and the like.

For some reason, whenever I see that word in reference to programming, I want to run screaming in the opposite direction. Does that make me a bad person?

Re:You had me right up to "Agile."

[justinlee37]

I had the pleasure of recording a graduate-level CS class taught by Chris Gilmore at Portland State University on agile methodologies. A lot of what he said actually made a lot of sense. You should give agile an honest chance.

Re:You had me right up to "Agile."

[mellon]

Of course it makes sense. Otherwise it wouldn't have gotten popular. The question is, does it *work*, or is it just a nice theory?

Re:You had me right up to "Agile."

[dubl-u]

For some reason, whenever I see that word in reference to programming, I want to run screaming in the opposite direction. Does that make me a bad person?

I'd say it means you've had managers.

There's no denying "Agile" is a fad, and a lot of people are doing fake-Agile, where they adopt some buzzwords and then carry on doing shitty work.

Luckily for me, I got interested in it before it was popular, so I don't have the same natural aversion. Personally, I've found a lot of value in the approach. For me, it has totally ended arguments about what's in scope, what the spec is, and whether or not a change is allowed. I no longer work to arbitrary dates, and I produce code I'm generally proud of. I've got some issues with it, and especially with the fad, but overall, I'm pretty happy with agile approaches.

Write your code backwards

[Colin Smith]

It's much easier to write parallel code that way.

 

Allow me to make a bold claim

[Griffon26]

Any code where the number of threads is not determined by the design is trivial parallel code.

Re:Allow me to make a bold claim

[dilvish_the_damned]

Right, so say we made a system that created threads to do heavy analysis on files, and then we make the number of threads dynamic depending on the hardware, because its dynamic it becomes trivial?

I would not call that claim "bold". I would call it something else...

Re:Allow me to make a bold claim

[Griffon26]

No, if it can be made dynamic it was trivial parallel code to begin with.

And note that I'm not saying that all code (e.g. analysis) was trivial, just the code to make the threads communicate.

Superflous

[jDeepbeep]

I don't see who the audience is going to be, aside from n00bs. No senior dev is going to buy this unless it's for a hint hint type of gift to a less-experienced colleague.

If you're in the field, you either know this stuff already and use it (won't be purchasing the book), know this stuff and don't use it (won't be purchasing the book), know this stuff and don't care (you wouldn't be pained to go purchase a book about it).

Bob's really chosen a microscopic target reading audience imo.

Re:Superflous

[Anonymous Coward]

You should look at the book. Marketing aside, Bob's recommendation as to what "Clean Code" is differs from 99% of the code that's out there. The bigger problem is that most of those 99% think their code is "hot shit" and will convince themselves that there's no room for improvement.

ARG!!! Looks like COBOL

[bb5ch39t]

Variable names like MAX_STUDENTS_PER_CLASS??? That looks like COBOL! My head! oh, my head! What ever happened to that Microsoft notation?

Re:ARG!!! Looks like COBOL

[Anonymous Coward]

Variable names like MAX_STUDENTS_PER_CLASS???

It should be MAXIMUM_STUDENTS_PER_CLASS. That way, there is NO doubt as to what value it is intended to contain. :]

whitespace

[doti]

you can't get cleaner than that!

The 10 Line Perl Script that Cost Us $1000 per Day

[c0d3r]

Some idiot in IT for a startup I worked for wrote some perl script that checks to see if our web page was up, and if it was down, it emails to 6 pages. Our ISP had a problem, and there were some other network issues and everyone just turned off their pagers and the script was constantly sending e-pages to all 6 pages, for a total for $1000/day. I guess the idiot didn't space out the times between checking the web site and paging, as it just constants sent e-pages. WTF!

Re:The 10 Line Perl Script that Cost Us $1000 per

[stubob]

Sounds like a problem with cron, not with the script. Integration, not unit test.

Quite Useful I think

[Thyamine]

I like these types of books because as the lone developer for a consulting company, I don't have much of a chance to interact with other devs. We mostly focus on everything else, with me left to do any and all the software work that comes up. I've been out of school for almost 10 years now, and it's nice to find something that helps remind me of different ways to do things, or things that will help me later (or someone that may come behind me).

Code Complete

[Anonymous Coward]

Another excellent book is the book Code Complete published by Microsoft Press. Lots of really good advice for who to write good code and maintainable code.

New hires at WinTellect have to read it. Mandatory.

Re:Code Complete

[I cant believe its n]

I'd suggest Effective Java by Joshua Bloch.

The best resource for clean code...

[Anonymous Coward]

can be found here

Re:The 10 Line Perl Script that Cost Us $1000 per

[sergstesh]

And what does it have to do with Perl ?

A one / two page version of this book?

[jelling]

Does anyone know of one or two page summary of this book / general style recommendations? I manage a software development team, and while I'd like to have everyone read this, I think it may be more reasonable to give them a "cheat sheet" of sort.

At the very least, some would take to it immediately and they could always use it as a reference for enforcing things later.

Re:A one / two page version of this book?

[Anml4ixoye]

[I'm the reviewer]

There are several resources out there. For example, here's the code conventions for Java:

http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html

The best thing is to simply find out what your team is doing and document it. Then read the book to see if there are ways to improve what you are already doing.

If you'd like to contact me, I'd be happy to talk about what I've done with my teams (foyc at cornet design dot com)

Why so difficult.

[DoktorTomoe]

Just follow one coding standard and stick to it, preferably a aerospace and/or military related one (as those are the ones that happen to be the best worked-out I've seen).

Personally, I prefer 2RDU00001, because not only it has the rules, but explains why every single specific rule makes sense, thus making it easier to enforce in a team.

Re:The 10 Line Perl Script that Cost Us $1000 per

[I cant believe its n]

Well, if it would have been written in LISP, it would only have taken 4 lines.

M104 Sombrero

[snooz_crash]

The book's cover is the Sombrero Galaxy.

Mod parent informative!

[Spy der Mann]

The mentioned diagram is the original source of the whole joke.

Coming Soon: Open Mic Coding Night

[tobiah]

At a coffee shop near you!

Re:The 10 Line Perl Script that Cost Us $1000 per

[sfjoe]

Sounds to me like the problem was with the idiot who signed a SLA allowing for that much downtime and to the owners of pagers for turning them off without investigating. IT worked as it should have.

Today I abused the preprocessor

[Anonymous Coward]

By including files multiple times, but with different macro definitions each time. One include sets up the actual function bodies, another sets up an import table, properly prototyped to be typesafe, another generates little assembler stubs that need decorated names to work okay, another... and so on. This involved writing preprocessor macros that inserted comma's between, but not before or after, a list of whitespace delimited arguments. That the comma has a special meaning to the preprocessor didn't help, but it works now. Not clean, perhaps, but this way I can keep related definitions in different places consistent automatically, eliminating a lot of potential human error and forgetfulness.

Clean Code is an oxymoron.

[TheCybernator]

that's it. said it all in the subject. continue scrolling down.

Re:fp

[jemminger]

"you ladies" - new here?

So antithetical to what software should be about

[cjonslashdot]

It is probably a wonderful book. But the very concept of "clean code" is, to me, a pre-occupation with the wrong things. It is as if the designers of the Large Hadron Collider were most concerned with the neatness of the machining of parts. What about design? What about patterns? Code is a means to an end, not an end in itself.

How the hell

[Anonymous Coward]

How the hell can you review a book that is not even available for the public to buy?
Smells like Slashdot Pepsi.

If you like this ...

[freddy_dreddy]

... you might want to add "numerical recipes" to your wishlist:

http://www.nrbook.com/nr3/

same thing with mailing lists in the old days

[freddy_dreddy]

When mailing lists where still massively used, a new feature in mailboxes upped emails an order of magnitude overnight. The feature is still among us: "auto-reply when absent" and caused mailing lists to send out new digests every time it got an out of office reply. Registered users got a new mail every minute or so, each time growing in size as the old message was included.

Seemed like a good idea at the time

[l0perb0y]

Behind every WTF moment is something that seemed like a perfectly reasonable idea at the time.

Little Coding Habits

[Anonymous Coward]

Every programmer has his own little set of tips'n'tricks when coding, ranging from indenting in source code, to using brackets & keep code organized. Some examples can be found here (http://www.mattiasgeniar.be/programming/little-coding-habits/), and it's what makes it challenging for us to work on group-projects, where everyone uses his own methods and ways to organize his/her code.

clean code?

[SuperDre]

It's all in the eye of the beholder... What you think is clean code doesn't mean someone else thinks the same about it.. Everybody has his/her own favorite way of doing stuff, and for them it's clean, but for others it isn't.. I have seen it so many times now.. someone who tell's you there is a rule to cleancode it lying, those are his rules... as I said, cleancode is something in the eye of the beholder...

Good Code

[liquidsilver10]

Found this a while ago, tend to agree with most of it ;) http://gwaredd.blogspot.com/2005/08/good-code.html

Or edit Wikipedia templates

[p3d0]

Some of them have to be seen to be believed.

AKA ASW

[Anonymous Coward]

Sometimes we stare at something that, for the life of us, we can't understand how it came out of a human mind (or, as the book puts it, has a high WTF/minute count)

Alaso known as the entire aSmallWorld codebase.

In the middle of readin the book

[CharlieG]

I'm in the middle of the book, and so far, I haven't seen much that I haven't seen before. In other places I think the author misses things, or I just plain disagree

Example Miss:
I the section on comments, he misses one of the most import reasons to comment/type of comment - the explaination of WHY you used a particular algorythm. I have a real life example - In one of my projects, there is a vendor API call AAA that seems to do exactly what we want, but it has 2 HUGE problems, the first being that despite the vendors docs claiming the API is thread safe, it isn't (this has been confirmed by the vendor), and if you use the call one item at a time, the 80ms each call takes kills us on our large data sets (the data set we use is something like 15x the size of the average customer). So, we developed a hybrid method that uses 2 different API calls, which ARE slower for 1st call (about 115ms), but then we can do the rest of the work locally. The comment documents WHY we are doing this, points to a longer document in the SCS that explains the details

Example disagree:
He uses the example of a gas tank and an interface. The "Bad" interface gives you CapacityInGallons and GallonsRemaining, while the "Good" interface gives you "PercentageOfFuelRemaining". Frankly, in most situations, I'd want to know what the first interface gives me - If I hook a 5 gallon hydrogen tank to the the space shuttle, I can have 100% of the fuel remaining, but I'm NOT going very far. Percentage of fuel remaining is useless unless you know what size the tank IS