Coding Notes

A few months ago I was working on some code that someone else had written. I was trying to add a feature into a class and couldn’t seem to figure out how the class worked, and thus couldn’t figure out where or how to implement my addition. After reviewing the code for a while I started to understand what was going on in the code and had a good enough understanding of it to then implement my new feature. The problem was since I then understood what the code was doing and how it worked I also felt compelled to restructure it, perhaps in a more logical order, or just change it so that it would be easier to understand later on. My problem was that after thinking about a new way to structure that class I wasn’t really certain about why that would be a better alternative, it just seemed better. So after wondering why it seemed like a good idea I decided to do some research into how to write “better” code, and why “better” code is “better”. My research ended pretty quickly as I remembered a few of my workmates talking about the book “Clean Code” a while back and how it discussed what makes “better” code. So I went to my local bookstore, picked up a copy, and started reading it.

Clean Code: A Handbook of Agile Software Craftsmanship was written by Robert C. Martin who has previously published books (which I have not read) on software engineering. He opens up Clean Code with the classic “WTF” comic of software quality, you know, the one that describes good code as code that produces the least “WTF’s per minute”. This is a really good example, since, that is exactly the kind of experience that got me to pick up the book. Martins purpose for the book is to present ideas on how to clean up code, and reduce the “WTF’s/Minute”, and make it easier for others and you to understand and modify later on. The first thing that Martin discusses is the problem of bad code, what it is, how it happens, and what the long term results are (maintenance, lots of maintenance). He then quickly transitions into a discussion of what clean code is, he asked several senior and well recognized software engineers what clean code is, and then lists their responses to get things started. After a brief overview of what clean code is, its off to the races, in depth analysis of clean code techniques and plenty of code examples to go along with it.

By far this book is not a quick read, or at least it shouldn’t be, most of the code examples that Martin gives are given first in the difficult code to understand context and then cleaned up into a clean code example. This method of actually showing the before and after code samples, if actually read and understood, gives immense meaning to the ideas that Martin gives on how to produce clean code. That being said, it is because of these code samples that this book is a bit of a slower read. Martin also encourages his readers to take the time to understand the code changes, warning that by not doing so you will miss out on the real understanding of why these code changes are occurring.

Martin begins the clean code concepts with fairly cosmetic issues, naming conventions, class and method sizes, comments, and formatting. These issues are fairly light on the technical scale (with class and method sizes being a bit more difficult) however, Martin does a good job of showing the benefits of implementing these clean code concepts. Then Martin goes into a discussion of more technical issues, error handling, objects and data structures, crosscutting concerns, system wide organization, testing, and even some discussion of concurrent programming. All the while he discusses not only good principles but why they are good principles, and gives examples of how to apply them. On some issues Martin admits controversy surrounding issues and clarifies why he came to his conclusion, as well as what others think. Martin then finishes the book with three chapters which take entire classes from well know API’s and dissects them into better, cleaner code, using the principles previously discussed in the book. These sections, as Martin states, are necessarily slower to read, given the large amounts of code and the complex changes. However, by slowly reading through them and understanding the changes being made it helps to bring together all the concepts of the book and shows how large sections of code can be understood and cleaned.

In the end of the book are several appendices, one is an in depth chapter long analysis of some concurrent clean code concepts, which an excellent discussion of what makes concurrent code difficult to debug and how to clean it up. There is also an appendix that cross references the principles of clean coding with the code transformations made in the last three chapters of the book. This appendix makes the book a great reference to keep on the shelf after reading it.

Overall the book is incredibly helpful, especially to software engineers who are earlier in their career (such as I). Held within the book are many useful techniques that senior engineers have taken a long time to hone, and if you read and absorb the concepts I think everyone can learn something from the book. That being said, several of the concepts that Martin discusses are controversial. His opinion that comments are unnecessary if the code is well organized and named, and in general clean, is definitely something that could be hard to swallow (depending on your stance with commenting). Martin isn’t completely against comments though, just unnecessary comments (he still supports comments in API’s). One of Martins main arguments against comments is that they simply produce one more thing that has to be maintained later on, a valid point. But despite the few controversial ideas that Martin discusses, none of which does he force on you, the book is filled with many highly useful concepts and excellent descriptions of why they are good ideas.

In the end I really only had one major complaint about the book, which is the subtitle “A Handbook of Agile Software Craftsmanship”. It is my opinion that clean code can and should be produced in non-agile environments as well, which I don’t think Martin would disagree with. Clean code is by far easier to modify than unclean code, and so its applicability may be higher within an agile environment, but it is certainly still applicable in non-agile environments (where the requirements are more static). My favorite concept of the book is also in the title, the idea of software engineering as a craft, too much of the time it seems that software engineering is seen as “coding”. The idea that software engineering is just hacking up something that does what your manager asked for is outdated and I think this book gives a nice introduction to software engineering as a true craft that should be treated with care and responsibility. Instead of just writing code, we as software engineers should write code that is of high quality, something that is truly well-crafted.

After reading the book my coding style has changed, I try to write clean code the first time, instead of just getting it to work. I also have a better understanding of why certain coding changes are better than others, which is why I picked up the book in the first place, so it fulfilled my needs and then some. I highly recommend it for anyone that is doing any programming.

Next on the bookshelf is “Data Visualization: Principles and Practice” by Alexandru C. Telea.

I was recently visiting my library’s math section looking for some interesting recreational math reading. I enjoy exploring math because, while some people may not think so, I find that the same problem solving skills that go into math also seem to be utilized in programming, especially in algorithm development. With a math minor my idea of recreational math reading may be a little different from those that aren’t directly involved with math however, Ian Stewart’s book The Magical Maze sounded interesting and intriguing. I had seen Ian Stewart’s name previously while perusing my local bookstores however, I had never read any of his books. The reason that I chose The Magical Maze over the other books in my library was because of its subtitle “Seeing the World Through Mathematical Eyes” this intrigued me and upon reading Stewart’s introduction to the book I understood what he meant.

Stewart wrote the book as another form of his lectures at the Royal Institution’s 1997 Christmas Lectures for young people. Naturally, and as Stewart points out, the book takes a different form than the lectures and includes more material than he covered in his lectures. That being said Stewart’s intent, as the subtitle states, was to present the book as an overview of how to see various aspects of the world from a more mathematical standpoint. Furthermore the book is one of mathematical recreation and was not meant to be inapproachable by those that aren’t in the field of mathematics. This same recreation must have been apparent in his lectures at the Christmas Lectures as they are not a math specific lecture series. Ultimately, it seems, that Stewart set out to present the reader with a way to approach the world with math and not to require the reader to understand too much complex math ahead of time.

I found the book to be a refreshingly light and yet detailed exploration of various more complex and applied mathematical subjects. Stewart structures the book as if the reader is wandering through a maze and thus he creates a very enjoyable story like appeal throughout the book. This helps to create a constant longing to get to the next junction of this magical maze. Stewart explores the mathematics that go into many of the magicians math tricks (or number guessing games) and the history and math behind calendars and flowers in his first chapter. The ease of use of the book is apparent from this very first chapter as several of its topics deal with complex modulus operations, and yet Stewart approaches them from a beginners standpoint, explaining the modulus, while continuing to keep it intriguing for the non-beginner. This ease of use and intriguing nature of the first chapter is constant throughout the book as Stewart explores further topics.

After the first chapter it becomes apparent that each junction of the maze is to discuss a different topic. Stewart approaches almost all of the topics from a very applied manner allowing the reader to understand where they would encounter this particular topic in their everyday world. The book talks briefly on many topics including decision graphs and indirectly finite automata, symmetry, probability and statistics, exposing some of its trickery, Stewart even touches on chaos theory.

Something that delighted the computer scientist in me was the way in which Stewart approached Turing machines, while I already understood the topic Stewart approached it from a perspective that every one could understand. By first approaching very simple logical paradoxes and proofs Stewart quickly and understandably moved into a universal way to solve any problem, the Turing machine. Stewart even went into the topic of the halting problem and the logical paradox that creates the unsolvable nature of the problem.

Stewart goes into the topic of symmetry in quite a bit of detail as well and yet by exploring it from a more applicable standpoint he allows for anyone to approach its complexity. Employing mirrors and animal movements Stewart describes how symmetry can be both three dimensional and four dimensional (time being the fourth dimension). Throughout the book Stewart uses other people’s work as well as his own to apply the math in an approachable way to the real world. For instance he uses others work with train sets to explain the existence of a universal Turing machine, by structuring a train set in a certain way one can simulate a computer and create a train network that exhibits the traits of the halting problem! Oh the joy a train set designer could have with that!

Overall I found the book to be incredibly refreshing in that it covered so many topics and did so with application as its main focus, leaving the reader longing to understand more of how the world is mathematically inclined. Stewart very much accomplished his goal of providing an excellent applicable mathematical overview in an approachable by anyone format. I would highly suggest any computer scientist read it because Stewart is a mathematician thus he approaches many of the same topics that computer science students approach and yet he does so from a different perspective than the computer science classroom’s perspective. This different perspective allows for a broadening of understanding in the various topics that The Magical Maze touches on. For the non computer science reader, I would still suggest the book if only to discover why sunflowers have spiraling seeds, the book allows anyone to open their eyes to the incredible mathematical universe that we live in, and provides a general appreciation for its mathematical complexity.