HN Books @HNBooksMonth

The best books of Hacker News.

Hacker News Comments on
Clean Code: A Handbook of Agile Software Craftsmanship

Robert C. Martin · 31 HN comments
HN Books has aggregated all Hacker News stories and comments that mention "Clean Code: A Handbook of Agile Software Craftsmanship" by Robert C. Martin.
View on Amazon [↗]
HN Books may receive an affiliate commission when you make purchases on sites after clicking through links on this page.
Amazon Summary
Even bad code can function. But if code isn’t clean, it can bring a development organization to its knees. Every year, countless hours and significant resources are lost because of poorly written code. But it doesn’t have to be that way. Noted software expert Robert C. Martin, presents a revolutionary paradigm with Clean Code: A Handbook of Agile Software Craftsmanship . Martin, who has helped bring agile principles from a practitioner’s point of view to tens of thousands of programmers, has teamed up with his colleagues from Object Mentor to distill their best agile practice of cleaning code “on the fly” into a book that will instill within you the values of software craftsman, and make you a better programmer―but only if you work at it. What kind of work will you be doing? You’ll be reading code―lots of code. And you will be challenged to think about what’s right about that code, and what’s wrong with it. More importantly you will be challenged to reassess your professional values and your commitment to your craft. Clean Code is divided into three parts. The first describes the principles, patterns, and practices of writing clean code. The second part consists of several case studies of increasing complexity. Each case study is an exercise in cleaning up code―of transforming a code base that has some problems into one that is sound and efficient. The third part is the payoff: a single chapter containing a list of heuristics and “smells” gathered while creating the case studies. The result is a knowledge base that describes the way we think when we write, read, and clean code. Readers will come away from this book understanding How to tell the difference between good and bad code How to write good code and how to transform bad code into good code How to create good names, good functions, good objects, and good classes How to format code for maximum readability How to implement complete error handling without obscuring code logic How to unit test and practice test-driven development What “smells” and heuristics can help you identify bad code This book is a must for any developer, software engineer, project manager, team lead, or systems analyst with an interest in producing better code.
HN Books Rankings
  • Ranked #6 all time · view

Hacker News Stories and Comments

All the comments and stories posted to Hacker News that reference this book.
If you just want to write better code literally, then consider reading Clean Code[0].

If you want to dive deeper in to Computer Science and become a Software Engineer, then there's a lot more to learn. Here's some short tips:

- Learn a few programming language for their paradism: Java (OOP); Python, Hashkell, Scala (Functional Programming), Rust (memory safety). You don't have to actually work on them, just need to be able to write some algorithm and know their key features.

- Read more code, especially those from high quality projects.

- Experiment a lot. Don't just read articles, blog posts. You have to get your hand dirty.


Nice list. Appreciate it. But I see there are a few amazing software books missing from the list such as:

- Clean Code (by "Uncle Bob")) []

- Design Patterns (by "Gang of 4") []

- Introduction to Algorithms (by "CLRS") []

Introduction to Algorithms might not be the best thing to start with. The name is very much misleading
Glad to see I'm not the only one who thinks this - it's one of the many areas I need to look at, and saw that recommended elsewhere... took a look on Amazon and got completely intimidated! If 1000+ pages is an introduction, what does the chapter and verse look like?

(I've started reading Grokking Algorithms this week, and it's been a much better introduction - I know it's not as in depth as some other books, but I'm making good progress with it and not drowning in complexity from the get go)

Don't let its size intimidate you. Introduction to Algorithms is quite approachable and its chapters are pretty well self-contained.
Thanks - I'll keep that in mind (although I'm old and attempting to retrain, and have found lots of things more difficult than everyone else appears to!)
Those are all there. With the nicknames as well.
A book about the design patterns is a good idea, the original book by then the gang of 4? I disagree, IMHO this book isn't well written, now the question is: is there a better book on this topic?
Head first is a much better option IMO
I'd recommend the following:

Clean Code: A Handbook of Agile Software Craftsmanship [0] is a great book on writing and reading code.

Similarly, Clean Architecture: A Craftsman's Guide to Software Structure and Design [1] is, no surprise, a book on organizing and architecting software.

Designing Data-Intensive Applications [2] may be overkill for your situation, but it's a good read to get an idea about how large scale applications function.

The Architecture of Open Source Applications [3] is a fantastic free resource that walks through how many applications are built. As another comment mentioned, reading code and understanding how other programs are built are great ways to build your "how to do things" repertoire.

Finally, I'd also recommend taking some classes. I started as a self-taught developer, but I've since taken classes both in-person and online that have been a tremendous help. There are many available for free online, and if in-person classes work better for you (motivation, support, resources, etc), definitely go that route. They're a fantastic way to grow.





Thanks everyone, the comments are much appreciated. Here's a list of books and other media resources recommended so far in the thread:

Robert C. Martin, Clean code:

Vaughn Vernon, various:

Steve McConnell, Code Complete: 2

Clean coder: videos

Hunt and Thomas, The Pragmatic Programmer:

Hitchhiker's Guide to Python:

Dustin Boswell The Art of Readable Code:

John Ousterhout, A Philosophy of Software Design: This one looks particularly interesting, thanks AlexCoventry!

Kent Beck, Test Driven Development:

Dan Bader, Python Tricks: The Book:

Ian Sommerville, Software Engineering:

Svilen Dobrev, various:

Skip anything by Robert Martin (clean coder series) and read at first Ousterhout and then McConnell instead.

Martin is well intentioned, but very dogmatic about some things like TDD, functions size, personal responsibility, etc. You need to already have some decent engineering experience to be able to detect and ignore the harmful stuff from his books.

I'd like to re-emphasise sanderjd's point not to focus too much on reading books. I myself went from doing a PhD and a lectureship in mathematics (with some coding here and there) to a decent software engineering job in a smallish company. I've learnt everything on the fly by reading code, searching stack overflow, trying stuff out and coding alongside others. The great thing coming out of a PhD is not just that you have to be pretty smart to have done it: you now know you can grasp almost any aspect of human knowledge with sufficient brain racking. This is a vastly underrated piece of self-awareness which enables one to stay humble and tenacious.
Yeah, I think of a PhD as a kind of intellectual adolescence. It led me to far greater intellectual independence.
There are a lot of good recommendations here, and I certainly relate to the instinct to go to books when you're looking to level up a skill set, but I really think what you need is not a bunch of books to read, but a few people to watch do the work. The only real way to do that is to get a job alongside them. You can read the books at the same time; you can ask your new coworkers which recommendations they agree with and read those ones first.
Yeah, software engineering is a craft, and generally the only way to learn those fast is to learn from others.
It's not a craft, in its purest form it's an engineering discipline with specific rules, procedures and standards.

The crucial point is that most of us a doing programming, and not software engineering. Learning from others is hit or miss. One can certainly learn to program from others, but that's not enough to be able to do software engineering.

Convince me that its "purest form" is an engineering discipline rather than a craft. What distinguishes it from things that you would agree are crafts? Or are all crafts actually engineering disciplines in their purest form?

I think this is a pretty interesting question. Personally, when I was young, I would have said what you said: it's engineering, specifications go in and properly engineered finished product come out. I was proud that my CS program was contained in an engineering school and that all my friends were in other engineering disciplines. The longer I do this though, the more I think it's a craft: fuzzy idea is put to a skilled practitioner and through discussion and creativity, one or more artifacts are created to satisfy that idea. You could argue this is true of more traditional engineering disciplines as well, and I would probably agree. I'm not totally sure what the distinction between the two things is. So tell me what the distinction is and convince me what we do is more the one than the other.

For what it's worth though, apprenticeship is also a very important part of engineering education. At some point, you have to see people do the thing, regardless of whether it's engineering or a craft.

When we say software development is a craft, we're saying that it's like shoemaking, pottery or woodworking.

Can the immense complexity of today and tomorrow's software be tamed by applying the same principles of building a cupboard? No, it requires an engineering mindset.

We're now limping along as an industry and it's not obvious because SW is bringing in massive amounts of money and we can basically get away with a lack of quality.

"When we say software development is a craft, we're saying that it's like shoemaking, pottery or woodworking."

The point being, there are intricate details that are very hard to deliver in the traditional class-room oriented school environment with well defined requirements.

Those do not state anything about scalability. Crafts can scale - like for example how the old giant cathedrals and castles were built in middle-age europe.

They don't say anything about mindsets either. You need an engineers mindset to buid a cathedral or a castle.

The specific problem with crafts is that adapting to new requirements is a complete hit and miss process. The reason for this problem is the lack or proper theoretical framework in which to pose ones work and into which embed the requirements themselves.

The program verification people are working towards solving this problem, see for example Leslie Lamport's work in TLA+.

But until we have a general, mathematical proof backed compiler for requirements, as well as for the program implementation, we are pretty much stuck with craftsmen.

(Well, we have proof compilers but those are at the moment completely unusable for general programming since they are so complex to use.)

"It's not a craft, in its purest form it's an engineering discipline with specific rules, procedures and standards."

Sorry, but I have to strongly disagree. In it's purest form the core of software engineering - i.e. programming is a craft. The other parts are mostly about creating processes so that craftsmen can create something together without stumbling into eachother.

The difference between a craft and engineering are numerous.

- engineers generally need a license

- engineering is about repeatability and creating dependable cost estimates

- engineers are required to study for years for a very good reason. You can be a rockstar programmer out of highschool.

Just having a bunch of cargo cult gibberish bound into a book does not make a craft into an engineering discipline.

It's harmfull to call programming engineering. Engineers have curriculums that can teach them pretty well what is expected of them once employed.

Not for programmers - or, well, software engineers. If there was even one curriculum that could churn out good programmers dependably, don't you think this model wouldn't be copied instantly elsewhere? If such a curruculum existed, do you think think software interviews would be filled with whiteboarding just to check out that the candidates understand even the basics?

I think this incapability to create a curriculum for actually creating good programmers is the best evidence that programming is a craft. It's such a complex topic that you can't create a mass curriculum that would serve all equally. Not with our current understanding, anyway. Maybe if we could teach everyone assembly, and Haskell , and have them implement compilers and languages as a standard things would be different.

The second best way to learn programming without being born a programmer savant is to learn from others while doing. Apprenticeship is the traditional way to train craftsmen.

Programming is so much more like a craft than engineering that it's best to call it a craft.

Craft is not a deragatory term. It just means we don't understand it theoretically well enough to teach it properly.

I tend to come down on your side of the craft vs. engineering debate, but then I disagree with basically your entire argument for it :)

You list three distinguishing features of an engineering discipline. The first and third swap cause and effect; a field doesn't become engineering because once it requires licensure and years of study. Surely you wouldn't agree that a successful campaign to require those things for software developers would bestow the status of engineering upon the work.

Your second point seems closer to the truth, but I'm not so sure it's true. If someone comes to a civil engineering firm and says, "design us a road between this city and that city", that is often a unique challenge because the terrain between those two cities is likely unique, maybe it requires a big bridge or a tunnel, which will be akin to but not identical to other bridges and tunnels you've built before.

"The first and third swap cause and effect;"

Sorry, I wrote that in a hurry. I wasn't claiming either was a cause or effect. It was more of finding characteristics that we can use to identify one from another. I.e. following the argumentation "If it quacks like a duck and walks likes a duck it's likely a duck, and if it doesn't, we don't really have much evidence of the duckish quality of the observed thing".

So, I was not aiming to claim that licensure would turn software engineering into actual engineering. Rather, that the requirements of the field are so poorly understood in the general context that there would be very little to agree on the specific requirements. Poorly understood -> not engineering, really.

I totally agree with what you wrote above.

On the third point: I'm not claiming 100% truthiness to my argument, but it's pretty close. Software engineering projects are still among the riskiest ventures where you can think of investing capital in. If you want to build a road:

1. The language of the requirements are pretty well understood, from point A to B, this many lanes 2. Unless some unforeseen calamity arises, and you have the capital to pump to the project, eventually you will get the road

I think we can agree that these define any engineering project. Of course, engineeering is not cut and dried either - that's why you need to have actually trained professionals who can react to the events that come along as the project progresses.

I don't think 1. or 2. can hold for a software project in the general sense. Furthermore, you can end up accidentally, without anyones fault, wasting an arbitrary amount of capital on a feature that could, in the worst case, be replaced by a few lines of Python.

This poor quality of our general understanding of software development and lack of common language to describe anything means that most of the time software develoment is closer to R&D than engineering.

Generally, you can get better estimates when you are implementing a similar project the nth time. Like some general website, or a server backend. And in these instances you have the language to describe features and requirements. But in the general sense, software development isn't anything like this.

Software development as practiced now by a huge number of individuals and companies is closer to a craft, but it can be and must be more than that if we want to be able to tackle the growing complexity of software and improve its overall barely adequate quality.

Crafts don't scale and are a poor fit for highly complex domains.

The curse of software development is its huge financial success, anemic legislative specification and the observed reality that customers will still buy poor quality software.

These are preventing the craft-like programming from turning into software engineering, but the craft is already failing to reach expectations: countless security disasters, unethical programmers enabling spying on millions, software literally killing users. This stuff will only get worse.

And finally, we do understand software engineering well enough to teach it properly. It's just not done, because it's not considered necessary when one can get by with a computer science degree, no degree or a bootcamp certificate.

"And finally, we do understand software engineering well enough to teach it properly."

This is news to me. I would very much like a citation, please. Or do you mean applying formal proof verification to everything?

Engineering doesn't mean using formal methods or specific fancy proofs, it's a systematic, disciplined quantifiable approach to software. It's described in an ISO standard and the more approachable IEEE SWEBOK.

The above is neither widely known (I only found out about it after many years of doing professional programming), nor is it necessary in order to be successful in the profession and/or make a lot of money.

Commercial software development is mostly a wild west and we're calling that craftsmanship.

I'll supplement this good advice by recommending pair programming. You will pick up a ton of stuff just sitting down at one keyboard with another programmer.
2340 (the mandatory group project course) also covered a lot of this stuff, though not in as much detail.

The suggested reading for that course is a book that blew my mind when I first saw it as an undergrad: Clean Code by Robert Cecil Martin. I believe the examples are all Java, but the lessons are applicable to any language. Stuff like naming your variables more carefully than you name your children.

- don't only worry about code or getting features shipped, but about the process, how to deliver quality.

- behind any given reason, there is a complex network of real reasons. You don't need to second-guess any decision/order/suggestion, but it helps understanding.

- most user stories / user requests are raw diamonds waiting to be polished. ("What do they really want me to solve")

Essential reading list:

- Clean Coder and Clean Code

- Test Driven Development by Kent Beck

Yes, yes and yes.

It's funny because technically, none of these three things are part of an engineer's job.

But once you do them, you start noticing how you eventually get to: - save yourself time - save your customer money - avoid unnecessary complications down the road - offer useful comments / feedback / critiques / alternatives, when need be (because you better understand the decisions made around you) - help your customer or team better understand what they really want - find yourself in a better position to transition to other roles, if you choose to

Btw, I wrote a blog article a few days ago about exactly this:

This: most user stories / user requests are raw diamonds waiting to be polished. ("What do they really want me to solve")
I really didn't enjoy the clean coder. There was a strong feeling of "Management is trying to screw you over, this is how to protect yourself from them". If your really working in that environment, you should probably just leave rather than having to resort to tricks and techniques to manage management. There seemed to be some other silly advice (I.E. I used to listen to music and code until 4AM and then not remember what I wrote. Clearly the music was to blame.)

I'm sure that Rob is a great employee, and the book does have a few good points, but I'm not sure I took away a whole lot from it.

interesting, reading your comment, I would never guess that we are speaking about the same book. I found it to be more of a guidebook to precise communication with colleagues and management.
read clean code

and clean coder

If you follow the (admittedly pretty extreme) advice in these books you will be in the top 10% at least.

He does reference it in both the first and last paragraph!

my fave is clean code... though uncle bob seems divisive these days for some reason.

For writing clean code, I highly recommend Uncle Bob's "Clean Code":

Check out the guys over at 8th light:

Uncle Bob in particular (the author of Clean Code[0], The Clean Coder[1], and the Clean Coders videos[2]) is a lot like Wozniak.




Yeah, what's missing is a software build by Robert Martin that is used and admired by several people.

Considering software is much more easily distributable than hardware makes the fact that there is none works against him.

Robert Martin may be good at Marketing, but I've never seen something from him that I liked.

Closer to Woz would be people who ACTUALLY shipped working code (Linus Torvalds as an example) then people who like to complain about code not having enough test coverage

So yeah, I hold no respect for this "Uncle Bob" guy

I was responding to the parent who said:

I wish there were (more?) people who feel about software like Steve Wozniak feels about hardware. Because it is an art, a pursuit of perfection.

Didn't mention anything about shipping popular software, so I'm not sure where you're getting that metric from, but it's completely irrelevant to what OP was describing, and uncle bob fits OP's description perfectly. His talks show how passionate he is about code as a craft, and how he wants to strive for perfection. The popularity of his code doesn't take away from that (not to mention that Jobs played a significant role on Woz's end for that, so it's not exactly an apples-to-apples comparison either). The fact that Martin has good rationales to support his ideas is just an added bonus in that regard. I get the impression that he's disliked more just because people have a fear of falling into the 'java culture' than because of his actual arguments.

Also, Linus is nothing like Woz other than their shipping of popular products. Nothing against the guy, I'm sure we're all grateful for his work, but he doesn't seem to display the same kind of childlike wonderment of his craft like woz does.

Give them a free copy of Clean Code[1], I started to care about my code more after I read that book.

You cannot sit and review each commit, the best you can do is to make them care about code.


Any chance I get I make an effort to suggest this book. There is also another book by Robert C. Martin which I suggest called The Clean Coder[2].


Great post. If you want a even _further_ expanded version of this I highly recommend "Clean Code"[1] by Robert C. Martin, and I learned a few days ago that there is a follow up book, "The Clean Coder"[2] which I am yet to read

[1] -

[2] -

Came here to say this. Glad someone did.
About The Clean Coder:
Yes! Please refer to the image at [1]. It's also on the cover of the introduction of 'Clean Code' [2]. Everyone here has some code that they are not proud of. You should see it as a sign that you've learned from the experience of designing and developing it.

Want to steadily improve on non-production code? Try you're asked to solve 5-30min coding exercises and after can immediately browse the solutions of your peers. The short feedback loop helps you understand how you could've improved while the code is still fresh in your head.



My favorite rule is 4.1.1; always use braces even where optional. I think a small fraction of the economy may have been damaged by the bugs caused by the silliness of leaving out optional braces and then having another developer come along and, well, you know how that goes :)

As someone who once read the Sun Java Style Coding [1] (which at a quick glance, appears to be a super set of the Google style guidelines) standard years ago and found it exciting and very helpful material, I unfortunately did not get such a kick skimming through this. Perhaps it's because after having read Clean Code [2], I feel that there is much missing that can lend itself to better code.



Nothing personal with braces, but Java code is too verbose and it's so much pleasure, sometimes, when you can make it shorter.
More on braces, I am squarely in the Allman camp for the reasons described here:

It is amazing the old-style K&R still persists. I think there was one more reason it was preferred in the early days which is not mentioned in the aforesaid link: storage space which was also expensive. The K&R style saves a new-line char which would be a significant saving in large codebases.

Reading code with K&R braces is almost unbearable to me. I don't really know why, it just seems like a wasted line and visual clutter when reading code.

    } else {
just looks too good to be wrong. I used Allman style for my first ~10 years of programming, then switched to "compact" style†, and didn't find it a big deal to adjust. Brace concerns melt away just like parens do in Lisp.

† I think K&R does make use of new line braces, for functions.

I got around this mindset along the years, by learning about the importance of lowering the maintenance costs, improving collaboration and not depending on any single person to understand any given module or system.

Books such as "Code Complete"[1] and "Clean Code"[2] should help you with that transition.



As a recent college graduate, I can tell you that they still teach the comment everything everywhere method, and in fact for most of our programming projects, documentation was at least 20% of the grade. I professionally, do not comment, but instead, write "clean code" that can be understood simply by reading it. Anything complicated I comment, but usually that means I need to refactor and rethink my approach.

I highly recommend this book: as it changed my life when it comes to software development. I have a real problem with commenting everywhere as most of the time you'll find a lot of public String getName() with like a comment of //Gets the name, uh, durr its name is get name! If you create concise methods with one general purpose you can create very readable code. Definitely check the book out, it is a very good read.

Well done code has good variables, good method/function naming and small methods/functions. If you have those 3 parts, you won't need any comments because it's self explanatory.

Comments often tend to explain the same thing as the code exactly does and what you see w/o looking at the comment. Also, they tend to be forgotten - if someone changes the code, he/she often doesn't change the comment. As a result, you'll have an outdated comment which can confuse you.

I recommend "Clean Code"[1] for more info on this subject. Beside other chapters, there's a chapter about what's a good and what's a bad comment.


I've never come across self-documenting code that can explain "why," which is what I was seeking. The closest thing I've ever come across was a PhD student working on a system called Seurat, but even that was really metadata attached to the code (something akin to an SCM). I agree clean code can help with the "what" or the "how", but that's almost never the problem to begin with.

In any event, I was looking for solid examples, not a general discussion on whether comments are good or bad. We clearly are not going to agree on that point so we'll save the Internet another pointless argument :-)

Ok I might have misunderstood you ;) Well I'm not saying comments are generally bad. But I think a lot of comments can be replaced by better code :) Solid examples I can't really show you atm (I'm not yet there where I'd say from myself that I write the cleanest code ever) ;)
Robert C Martin (Uncle Bob)'s Clean Code is a great read and discusses good naming in exhaustive and occasionally alarming depth.

The first step is to be aware that you aren't writing succinct, manageable code - so you are already making progress :)

I'd recommend these books, mixed with some searching around for best practices for whatever specific framework/language/toolkit you are writing code with.

Clean Code

Refactoring to Patterns

Clean Code seems quite a bit more relevant and in-depth than this.

I am passionate about writing good code, and I'll try to offer some practical advice. As others said, the first step is understanding the importance of writing clean code and taking pride in your craft. By doing this, you are already ahead of most other programmers who don't really care. Now, how do you improve?

1) Read books.

With 4-5 years of experience, you already have a good intuition for "good" and "bad" code. Still, it doesn't hurt to learn more about it. There are a lot of good books on this subject.

The first is "Clean Code", by Robert C. Martin. It's the first book I read on this subject, and I learned a lot. Note that the book uses Java in the examples, but I think the ideas would apply to most other languages.

Its author, Uncle Bob ( ) has long been a proponent of writing clean, beautiful code. He recently did an interview for Xebia: (French blog, but the interview is in English). In it, he advises:

"Well there are a number of books that talk about writing code well. Kent Beck wrote a book called “Implementation Patterns” very recently. It’s an excellent book all about software craftsmanship. The pragmatic programmers wrote a wonderful book in 2000 called “The pragmatic programmer”, again a wonderful book. Chad Fowler wrote a book call the “Passionate Programmer”. Again the book is about doing everything well. I wrote a book recently called “Clean Code” which is very specific about particular things you can do with your code to do it well. So there is a tremendous number of resources that are available for people who are interested in doing software craftsmanship well."

Out of those, disregard "The passionate Programmer". It's an okay book, but its focus is on building a good programmer career, not on code.

"Implementation Patterns" by Kent Beck is a great book with a lot of best practices when writing * Java * code. Less useful if you use another language.

"The pragmatic programmer" is a good book on software craftsmanship. I'm personally half-way through. There is a lot of good advice in it, but I often find myself thinking it's "common-sense". Maybe because I've already been exposed to most of the ideas by reading blogs? Still, it's a great book, with a lot of best practices. It's main focus is not code, though, so you might want to start with other books if your focus is on writing good code.

To these books, I'd add "Code Complete (2nd Edition)" (language-agnostic) and "Effective Java 2nd Edition" if you use Java.


If you use Java, read:

  - Clean Code -
  - Effective Java 2nd Edition -
  - Implementation Patterns -
  - Code Complete / Pragmatic Programmer
If you use another language, read:

  - Clean Code -
  - Code Complete -
  - Pragmatic Programmer -
Other people might chime in with suggestions for other languages?

2) Practice.

Implement what you learned in the books. Keep improving.

3) Read other people's code.

Read good open source code. Not all code is good code. Ask around for OSS projects with good code in your language.

If you use Java, start with:

  - Google Guava -
  - Google Guice -
  - Spring Framework -
4) Practice.

5) Practice.

I believe it is important to also have a view and strategy for your career. Read "Apprenticeship Patterns."

I highly recommend the other books, too.

Cheers, Kevin

Thank you so much for the comprehensive reply. You are right when you say that with 4-5 years of experience I know to some extent what good and bad code is. but sometimes I think a lot and write the best code that i can, and later after some time i realize; by looking at some one else's code or by myself knowing a new feature of the language i am using, that i could have done it in a much better way .. that is much more beautiful. My problem is that if my code doesnt look like poetry to me, clean readable understandable i feel the need to improve it.
Other people have already said most of what I wanted to say – that self-explanatory code, and sometimes tests, is almost always better than comments. I just want to point out a good reference on this topic: the book Clean Code: A Handbook of Agile Software Craftsmanship [1], specifically Chapter 4, “Comments”. That chapter gives examples showing which comments should be turned into code and which are acceptable to leave as comments, and it explains the reasoning behind the choices. (And the rest of the book teaches you how to make your code self-explanatory and easy-to-read.)


The book that changed my life:

"Clean Code" by Robert Martin is one of the best programming books ever written, and it barely has any code in it. However, it is relevant for every programming language. He treats unit tests like mandatory rituals, though, and unfortunately, I have not progressed quite that far yet. Still, it is a must read and gives good insights into this topic.

"one of the best programming books ever written, and it barely has any code in it."

Sounds very fishy, but from Robert Martin, who thinks people who don't do TDD (not unit testing, TDD) are "unprofessional" and "stone age programmers", I wouldn't expect any less.

"He treats unit tests like mandatory rituals,"

cargo cult alert!

fwiw my conclusion based on my experience, unit tests are (by and large)a good idea. Test Driven Development is dubious, especially the "TDD is a design method" idea. Conflating the two notions isn't very useful but happens surprisingly often.

Even if you don't get into the TDD stuff he evangelizes, it's a pretty darn good read. It has some really thought-provoking things to think about in terms of how to write your code. I wouldn't dismiss it offhandedly.
HN Books is an independent project and is not operated by Y Combinator or
~ yaj@
;laksdfhjdhksalkfj more things ~ Privacy Policy ~
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.