Tim Harvey :: Blog

One domain moved…24 to go

2010-07-08T00:01:29Z

Yea, so I completely procrastinated on getting a bunch of domains off a server that I had setup with annual billing. Moving domains from one server to the next is one of the worst ways I can think of to spend time. I’d probably rather have a root canal.

Due to the hosts billing setup, I can’t go month-to-month. While that creates an awful headache as I have to move every site off NOW…it’s best in the long-run.

A friend of mine is taking over all my consulting clients so I will no longer be in the hosting business, nor responsible for clients sites if they go down. I still have a couple web-based services that I’ll continue to support for a while.

One or two will get shut down pretty quickly (Am I Down has already been open-sourced, and the Twitter Filter is next). ShipperTools is a bit harder to drop as it’s profitable. I suppose that the maintenance time on it is next to nothing, so I’ll keep it going for a while.

This site was the first one to shift over. Wish me luck!

PPL – Falling off the wagon

2010-07-07T12:56:15Z

This is part of the Peer Pressure Learning 30 series. Jump to my introduction to the experiment if you haven’t been following along.

Wow, this week has been a PPL catastrophe for me. The following are all lame excuses, but I’ll give them anyways.

The weekend definitely kicked my butt. The ladies have all been sick, so a number of late night compounded into me not getting up early and having zero energy to blog at 11pm. So there went Sunday and Monday.

Yesterday got really interesting. After doing a spontaneous 10 mile ride in the morning on the way to work (the most I’ve done before is 5-6 miles), I played soccer for 90 minutes in the evening. While I was about done, I realized that I have a VPS server that will expire within a day or two that needs migrated to a server run by a friend who took over all my hosting clients. AHH!!! These sites are so old that I doubt they (or I) have the best backups around. So into panic mode I went attempting to extend my server service and get sites moved. Not good.

On the bright side, Peer Pressure Exercise and Geek Fitness are looking great. I’ve biked to work for three straight weeks and am beginning to get some longer rides in. Gotta look on the bright side, right? GRIN.

So…I’m hoping to get back into it at lunch today, keeping the bleeding to just three days. If all goes well with the server move, perhaps I can get back on track before the Indy.rb meetup next week. If not, I think the heckling might be more than I can bear!

End of sob story…back to the code!

PPL: Day 20 – Successive Refinement Part 2

2010-07-03T13:15:50Z

This is part of the Peer Pressure Learning 30 series. Go read my introduction to the experiment that Miles and I embarked on.

Since this is a pretty meaty chapter, I want to take my time and really internalize the lessons here. Just like a University’s capstone course, these case study chapters should apply all the lessons that came before and help me see how it all comes together.

As such, I’m converting the example code into the Ruby equivalent. That will both make it familiar and push me to think through why I would make the various refinements. It’s also great to do some pure Ruby. I do so much that’s Rails specific that I like the opportunity to get back the the core language.

Today’s Reading: Reread pg 177 – pg 186

I skimmed ahead a bit since I covered the same material from yesterday. I realized that I was converting the nice, clean copy of the argument parser and probably shouldn’t. The text goes back in time to an earlier copy that’s pretty rough, then proceeds to show how it evolved. Oops. (I thought we would be taking the nice one…mucking it up with some hacky fixes, then cleaning it up)

So I’m taking a step backwards to code up the “bad” version in Ruby and will follow along with the improvements. Unless the tests are in the chapter (which I don’t think I saw), I’ll probably see about throwing in some rSpec as I go to fully TDD the whole thing.

Out of deference to the author and all the work he did on these examples, I won’t be sharing the Git repo. However, I’ll look for some chunks of code that I could post to illustrate interesting points.

What’s next

Always one to get going on the next thing…I’m already thinking about what I’ll do next month. The ideas I like best involve either creating an app from scratch and applying Clean Code principles, or perhaps cleaning up my Twitter Filter or Am I Down.

I may not be brave enough to commit to a full 30 days, but perhaps I can keep up the pace. Ideally, I would spend 30-60 minutes each day and post the repo and selected improvements as I go. My latest thinking is that I would implement Am I Down in Rails 3 with Reddis and maybe Mongo.

PPL: Day 19 – Successive Refinement Part 1

2010-07-03T02:52:33Z

This is part of the Peer Pressure Learning 30 series. Go read my introduction to the experiment that Miles and I embarked on.

It’s actually not too late in the evening and the whole family is asleep. It’s a good time to hit the Clean Code! The next couple chapters will be interesting to write about. There are several extended case studies, so it’s a change of pace. We’ll see what comes out of them!

Today’s Reading: pg 177 – pg 186

Well, not a lot to say for this first portion of the chapter. I will say this, I read a ton of code and need more time to digest it. Another run-through tomorrow will help.

The following made me really happy I don’t used Java:

It’s remarkable how much code is required to flesh out the details of this simple concept. One of the reasons for this is that we are using a particularly wordy language. Java, being a statically typed language, requires a lot of words in order to satisfy the type system. In a language like Ruby, Python, or Smalltalk, this program is much smaller.

I almost feel that to do this chapter justice, I should do just that; write it in Ruby. That way, I get a better feel for how it works and what’s going on as the program changes. I think I’ll lose too much in translation as I try to ignore the verbose nature of Java.

PPL: Day 18 – Emergence

2010-07-01T13:26:59Z

This is part of the Peer Pressure Learning 30 series, taking me through Clean Code in 30 days. Take a gander at my introduction to the experiment if you have no idea what that means.

The site I talked about yesterday, http://ErvsCafe.com is available on GitHub if you want to see the source. We’ll continue to update that repo as we improve the site.

I’m trying really hard not to treat this chapter as a throwaway. Clearly, the author included it for a reason, but it’s so small!

Today’s reading: Pg 171 – pg 176

This chapter was actually pretty darn good. It boils down a lot of critical concepts from the preceding text. Where the earlier chapters provided an excellent foundation of tactical (and increasingly strategic) methodologies, this chapter moved over the delivering some excellent big picture thinking. It summarizes the previous chapters beautifully using a few key rules from Kent Beck’s Extreme Programming Explained (which I’m going to reproduce from Martin Fowler’s blog):

In XPE Kent gives four criteria for a simple system. In order (most important first):

Runs all the Tests

Reveals all the intention

No duplication

Fewest number of classes or methods

There’s a LOT of meat there. I can see this heuristic becoming extremely valuable.

My biggest fault at this point is probably duplication. I really need to work on strategies for reducing duplication in my code. This challenges me to push harder on refactoring once my tests pass and the functionality works.

I really appreciate all the encouragement I’ve been getting to keep up the pace and keep the Peer Pressure Learning going.

PPL: Day 17 – Systems Part 2

2010-07-01T12:49:14Z

This is part of the Peer Pressure Learning 30 series. Jump to my introduction to the experiment if you got here from Google or some other site.

Several mornings this past week were taken up by building http://ervscafe.com/ with Vince. We did the site for free to help out the restaurant painfully stuffed into the 7th floor of our building. We love having Erv (his real name is Kevin) around to feed us. It’s a pretty ghetto site, but the idea was quick and dirty.

With that pretty well done (I need to do a bit to the Rails app so he can update his specials), I’m back to having a bit more time for PPL. Hopefully tonight will be my last weekday post done in the evening for a while.

Today’s reading: pg 164 – pg 170

While this chapter continued with a bunch of Java-specific framework details (Swing, JBoss, Beans, etc), one particular concept leapt off the page and seemed to have a potential impact on a large Rails app:

In Spring, you write your business logic as Plain-Old Java Objects. POJOs are purely focused on their domain. They have no dependencies on enterprise frameworks (or any other domains). Hence, they are conceptually simpler and easier to test drive.

Whoa! Can you imagine an entire Rails app that used Models as data containers and plain Ruby classes to hold all the business logic? It frightens be rather a lot, but the idea that all that business logic could be more easily transferred to another language, a different framework, or more easily modified sounds incredible. Separating persistence (and framework crap) from business logic sounds like win to me.

Downside? That seems to fight against much of the Rails conventions and common practice, so implementing a solution in that manner would require treading very rough, new territory.

I have a small portion of an app I did constructed somewhat this way. I’ve been wanting to write up a blog post on the topic as it’s a pretty in-depth implementation. This chapter gives me hope that I just might have been onto something purely by chance!

Another great standout from the chapter is the discussion of decision making. This nails it:

We often forget that it is also best to postpone decisions until the last possible moment. This isn’t lazy or irresponsible; it lets us make informed choices with the best possible information.

And finally, the best bit of all:

…never forget to use the simplest thing that can possibly work.

Well said.

Next up? Emergence. Again, I have no idea what that means, but it sounds impressive (it has to be, the word has 3 syllables).

Miles continues to bang out his PPL blog posts. His latest is on the Python framework Django (pronounced, “JANG-go”, I think).

Google: Please update the site i built

2010-07-01T03:04:00Z

Dear Google,

Your index is out of date and I’d love for you to revisit this site ASAP: http://factsandfiguresscotland.com/. Kthx.

Tim

PPL: Day 16 – Systems Part 1

2010-07-01T12:50:35Z

This is part of the Peer Pressure Learning 30 series. Take a gander at my introduction to the experiment.

Ok, I’m back on track with two blog posts today. My Day 15b – Classes Part 2 post fills in the gap left by my Day 15- FAIL.

I started into the rather heavy chapter on systems. It’s a higher level look at clean code from the architecture and strategy perspective. A ton of it was either over my head (and heavy into Java) or was tough to apply with my Ruby on Rails goggles on.

Today’s reading: pg 153 – 163

Wow, this was some intense stuff. Uncle Bob talked about some interesting pitfalls with coupling the instantiation and management of dependencies in with the business logic. I could see a lot of validity to the problems that causes as you get into larger and large codebases. The pain of changing out your ORM already leads me to believe that Ruby on Rails projects likely suffer from some of the problems he talks about.

He shared some interesting examples of how to decouple the initialization of your objects from the run-time code, but I couldn’t even begin to understand how that would relate to a Rails app.

I have to take a cue from Miles to make any sense of this blog post:

What I Think I Now Know

Think, think, think before you go charging down a path with your classes. The author showed an example of the ubiquitous lazy-loading method of instantiating objects that I’ve used numerous times. In addition to pointing out that it may be a pre-mature optimization, he also explains that it can tie the instantiation too closely with your business logic. What does one do about that? I have no idea.

Realize that your toolkit or framework may fight against what you’re trying to accomplish. While I don’t know what you’d do about it, we have to realize that any framework we use was designed with a purpose or set of goals. Those may be different that we we need to accomplish with the current work at hand. I’m not suggesting that we throw out frameworks, merely that we understand their strengths and weaknesses. And at the same time, we learn to see clearly when it’s time to buck the convention or stick to it.

Finally, one must accept that you can’t architect any system for the needs you’ll have in 12-24 months. It’s just not going to work out exactly the way you expect. As believers in Agile, we need to accept change and do what supports today’s requirements with basic consideration for the future. We need to be wary of over-engineering.

PPL: Day 15b – Classes Part 2

2010-06-30T02:28:11Z

This is part of the Peer Pressure Learning 30 series. Jump to my introduction to the experiment if you haven’t been following along.

Ok, it’s a day late, but I’m back on the wagon. It’s really day 16, but I’ll get back to that in a few moments. I need to play catch up first!

I have to make a brief digression. This Peer Pressure Learning has impacted a number of areas in my life. I’ve found that as I’ve been more focused and disciplined, other priorities have felt more effortless.

I’ve ridden my bike or walked to work almost two weeks now (with one or two breaks). That has paid off big-time for my soccer league. I’ve been a lot more effective on defense and logged my first assist today to bring us back from a 1-2 deficit. Geek fitness for the win! Ok, enough of that, back to the code!

I lucked out with today’s reading. The balance of the Classes chapter wasn’t particularly long. But, it was home to some great material about organizing your classes with an eye towards future change. It’s been said a thousand ways…and I’ll repeat it again here: the only thing in software you can be certain of is that you’ll have to change tomorrow what you wrote today.

Today’s reading: pg 147 – pg 152

I glossed over the Single Responsibility Principle of class design from the first portion of the text, but it was impossible to miss here. The idea is that a class with more than two responsibilities is a broken design. A couple ways to tell that one has broken the SRP (my paraphrasing from memory):

Describing the class in plain english includes words like “and”, “or”, “if”, or “unless”
Finding private methods that only support a few of the public methods or private variables used by a small portion of the methods
More than one type of application change will impact the class (meaning it’s probably doing more than one thing (see the first bullet)

It’s pretty genius. It leads to mountains of tiny classes. Coding this way must be a complete mind shift. One couldn’t do this haphazardly or you’d go crazy. Lots of tiny, but complex classes would be awful. You really would have to get darn good at simplification and organization. Thank goodness for tests, you’d have no way to complete a refactor otherwise!

A throw-in at the end talked about one of my favorite concepts (I like it, but probably am not that great at it): Separate stuff that appears likely to change from stuff that will stay constant. Don’t put them in the same class!

Why do you think we have configuration files full of application constants and don’t put that stuff into our classes? It’s partly to eliminate duplication, but just as importantly, it’s so our system can evolve through editing as few files as possible.

One of my other favorite testing methods was talked about as well. When you have to interface with some external class (one that’s perhaps complicated or an API), pass in the class as part of the initialization or using a setter method. That way, your tests can push in a mock object for easier validation. It also allows you to decouple your code from an external or volatile library. Nice!

Next up, Chapter 11: Systems (I have no idea what the chapter is about, but it sounds cool).

While I’ve been slacking, Miles has been tearing it up!

Day 14: HTML5
Day 15: Python

PPL: Day 15 – FAIL

2010-06-29T03:36:20Z

Yea, I managed to blow it today. It’s 11:30 and I just can’t bring myself to stay up another 30 minutes.

I’ll probably look to pit through two posts in the next day or two.

I’m working with a friend to build a free web site for our building’s cafe, so tomorrow will be tough. Wish me luck!

PPL: Day 14 – Classes Part 1

2010-06-30T01:54:04Z

This is part of the Peer Pressure Learning 30 series. The introduction to the experiment post will make all things clear.

Whew, I almost forgot tonight! That would have been my first miss. Luckily, after toying with the Facebook API and FQL for a while, it dawned on me that I needed to finish reading the chapter on Classes (which I started this morning) and blog!

Today’s reading: pg 135 – pg 146

Having read a chunk of Code Complete, thinking about clean, concise classes isn’t entirely new. I was pleased to find that Uncle Bob isn’t fanatical about perfection, sometimes bending the rules on privacy:

For us, tests rule. If a test in the same package needs to call a function or access a variable, we’ll make it protected…

Nice, that had been bothering me for a month or two. It seems that my larger classes end up with a private method or two that I’d like to test. They’re tested by virtue of the public methods being tested, but a targeted test would help at times. I didn’t like the idea of making them public, so this strikes a nice balance.

As with functions, the author makes it clean that they should be small, and then you should go back and make them smaller still. But…he makes a great distinction: “with functions we measured size by counting physical lines. With classes we use a different measure. We count responsibilities“. Oh man, genius!

Fighting with Rails

I’m clearly still new to Rails and find that the conventions seem to fight against the larger OOP concepts at times. I’m sure that as I get more comfortable with the plumbing (and hell, Ruby itself) that I’ll find all this easier. I read the following a struggle to know how to make such nice-sounding organization a reality in a world of “fat models”:

At the same time, many developers fear that a large number of small, single-purpose classes makes it more difficult to understand the bigger picture. They are concerned that they must navigate from class to class in order to figure out how a larger piece of work gets accomplished.

However, a system with many small classes has no more moving parts that a system with a few large classes. There is just as much to learn in the system with a few large classes. So the question is: Do you want your tools organized into toolboxes with many small drawers each containing well-defined and well-labeled components? Or do you want a few drawers you toss everything into?

It’s crazy stuff. While I like the idea of small drawers, I suspect that I would end up creating a ton of tiny drawers that don’t have the requisite organization. Time will tell!

PPL: Day 13 – Unit Tests

2010-06-30T01:53:13Z

This is part of the Peer Pressure Learning 30 series. Get a handle on this PPL thing with my introduction to the experiment.

It’s the weekend, so I’m back to the evening groove. The morning was relaxed and the whole family and I went to visit the Amish farm that we buy all our meat, eggs, and chicken from. But that’s another blog post.

Today’s posts is on unit tests. I’m trying not to be a snob as the Ruby community seems to really have testing nailed. Between Rspec and Cucumber, I’m in heaven. I have to remind myself that there’s a lot to learn from the Java community and especially about writing good tests.

Today’s reading: pg 121 – pg 134

Uncle Bob seems to nail me with every chapter. I have been, for the most part, a self-taught programmer. The programming courses I took in college were a joke that I dominated in my sleep, so I jumped over to a business degree so I could learn something I didn’t know. But therein lies the problem. Until now, I’ve never had a systematic approach to polishing my craft. This line from the text describes me to a T:

…in the mad rush to add testing to our discipline, many programmers have missed some of the more subtle, and important, points of writing good tests.

Some really good points come out of the chapter:

Test code should match the code quality of production code – I can relate here…test code changes all the time as the requirements change. If your tests are crap, you’ll pay for it every time you have to rewrite tests. Changing over to using Factories has been a perfect example. The tests stay DRY and have been much easier to maintain since the change. Uncle Bob (the author) correctly says: “Test code is just as important as production code.”
Tests give you courage – That’s a weird thing to say, and it’s definitely my interpretation of the text. But…it really is true. I have tremendous faith in the test suites I use in each of my apps. Because of the safety net they provide, I can rename large models, change big chunks of logic, or refactor sections of tricky code without fear. My tests tell me when I’m done! I couldn’t go back to a non-TDD (test driven development) language ever again (or one with sucky TDD tools). I really mean that. I’d be hard as hell.
One assert per test…probably – I like that Uncle Bob feels free to break the rules. While it’s a good goal to shoot for one assert per test, the added code and duplication may negate the benefit. I find that I frequently pair a record count assert with an assertion about what’s in the record. The better guideline is to test one behavior (the text says, “concept”) per test.

All in all, I feel pretty good about where I stand with test code. I definitely need to hone my comfort level with the tools I use, particularly to reduce duplication.

I’m totally pumped about tomorrows reading which begins a journey into the depths of classes and their proper composition.

If you’re ready to melt your brain on some wild code stuff, read Miles’ post on Factor, a crazy weird stack language that’s unlike anything you’ve even seen.

PPL: Day 12 – Boundaries

2010-06-25T12:47:31Z

This is part of the Peer Pressure Learning 30 series. The introduction to the experiment post will make all things clear.

Today’s already been a fun day. Vince, my partner in crime at the office, and I got up early and started banging out a free web site for our building’s cafe. It’s a great little restaurant on the seventh floor that needs some help with a bit of marketing. Look for http://ErvsCafe.com/ soon.

I also had a blast this morning reading about software boundaries. It’s a pretty important topic when you begin considering larger systems.

Today’s reading: pg 113 – pg 120

The general idea is that we need to manage how our code interacts with software written by someone else, or that might change frequently. It’s really another look at coupling.

Rather than sprinkling code all through our app that uses a particular gem, we’re encouraged to write a wrapper class so that it’s less disruptive (sorry Jerry). That way, we can swap out an uploader / asset gem with something else and don’t have to rewrite large swaths of the application’s code. This comment about such classes sums it up best:

It is able to evolve with very little impact on the rest of the application

There’s a wonderful gem in this chapter. The section on exploring and learning boundaries offers some excellent advice on getting used to and beginning to integrate a new library.

One of my big takeaways was the authors encouragement to write tests that exercise the new library. It forces you to begin learning the library’s API and documents your understanding. It also acts as a safety net when the library updates. You’ll know immediately if some portion of the API you are familiar with changes. These are the kind of test, in my world, that I’d leave for the CI server to run once they’re in place. There’s no sense in running them regularly unless you’re working with changing out that library.

Looking for some more PPL goodness? Take a peek at Miles’ Day 10 post on Erlang!

PPL: Day 11 – Error handling

2010-06-24T13:05:42Z

This is part of the Peer Pressure Learning 30 series. Read my my introduction to the experiment to learn more.

After two days on Objects and Data Structures, I felt like I was beginning to get a better handle on the concepts. I’m pumped about today’s topic as I’ve just been pondering how to handle bad inputs (to libraries) and thinking about alerting (to me) of recoverable error conditions.

Today’s reading: pg 103 – pg 112

This statement kicks off the chapter on the right foot for me, setting the stage:

Error handling is important, but if it obscures the logic, it’s wrong.

Nice. Definitely not playing around on this topic! This was particularly valuable as the discussion turned to null values in arguments and return values.

Two critical sections were particularly timely for me, titled “Don’t return null” and “Don’t pass null”. I had really been struggling with this and as a result, been adding .nil? checks all over my code. I just had a conversation about it yesterday and was at a loss about what to do.

Now, it’s funny because I failed to take several things into account:

Rails already has some great error handling, so if a null creeps in somewhere, the user gets a nice error message and Hoptoad helpfully kicks me in the mouth with a nice shiny stack trace.
While it’s definitely worth coding defensively, my code is the only code that calls the methods I’m worried about, so I can trap for bad user input long before it gets into the libraries.
Throwing exceptions is not a bad practice. I read a blog post talking about bad usage of exceptions to control program flow and have since stayed away from them. Dumb. In several cases, I’d been returning nil as a flag that something had gone wrong and allowed the caller to deal with it. That’s pretty lame. Thinking now, I realize that I could define some sensible exceptions and allow the caller to handle each differently depending on the situation.

Chances are good that most of my .nil? checks are pointless and only satisfy test cases that I created in rspec. Boo. Time to rip some stuff out because as they say, “No code is better than no code.”

So…all that to say, there’s some tremendous wisdom in what author Uncle Bob shares. He sums it up nicely by saying:

If you are tempted to return null from a method, consider throwing an exception or returning a special case object instead.

* Note: A special case object would be one that looks and acts like the typically returned object. For example, Rails ActiveRecord #all method typically returns an enumerated list of model instances. When no records exist, it returns an empty array instead of nil. That plays nicely with a .each loop, saving us from trapping for nil.

PPL: Day 10 – Objects & Data Structures Part 2

2010-06-23T12:11:52Z

This is part of the Peer Pressure Learning 30 series. You can read all about it.

Yesterday’s late morning led to a last-minute blog post. Thankfully, I read the text earlier in the day as it really warranted some consideration. Thankfully today, I’m back to the early groove.

Today’s reading: pg 99 – pg 102

The chapter’s concepts begin to take shape with the balance of the chapter read. While it’s really tough to see how it fits in with the rather opinionated Rails framework. I’d be rather interested in talking through concepts in this chapter as they relate to MVC.

The crux of the matter is the distinction between data structures (dumb classes that hold data) and objects (super-smart classes that operate on data structures). I quoted from the text yesterday, but really should have used this rewording of the Law of Demeter (a “well known heuristic”):

a module should not know about the inards of the objects in manipulates

That talks about objects, not data structures. The idea is that objects know very little about other objects in the system. They are allowed to chain through and know a ton about data structures, even if they’re chained several layers deep.

Ruby on Rails

So, what about Ruby on Rails? Clearly, the whole discussion is moot when you’re looking at a site/system with less than 5,000 lines of real code. It’s probably not large enough to worry about splitting into separate objects and data structures. Rails’ models hide enough functionality that a model can stay reasonably sized and satisfy the needs of a hybrid object / data structure. It’s a concern of balance, really. While a purist may demand that the smallest app utilize all the associated patterns and follow OOP to the T, I’m not in that camp. I’ve done enough consulting to realize that you have to balance cost (time) with the benefits (rather low in small projects).

A larger app begins to make the whole discussion rather interesting. I seriously have no answers on this side of the topic. If I’m taking the text properly, one would begin to make the models increasingly small, leaving validations and associations behind (and probably some of the callbacks). You’d then move more and more logic into library objects.

How the heck would that work? Hmm…I’m not really sure. I’ve done some work on having the model call a factory that instantiates the associated libraries, but I could also see some of that logic going into the controller. Putting it into the controller seems to be a great opportunity to duplicate code (not good). I think I like the idea of the model starting the process.

I’d love to hear from anyone with experience on really large, complex Rails projects. Talking through the concepts with someone experienced with 20-50k lines.

PPL: Day 9 – Objects and Data Structures Part 1

2010-06-23T11:11:13Z

This is part of the Peer Pressure Learning 30 series. Take a peek at my introduction to the experiment Miles and I embarked on.

This was a tricky section to get through today. I’m long past the comfortable passages that I’ve read over in the past and into the more conceptual material. I think it will require some more thought and review to really think through properly.

Today’s reading: pg 93 – 98

I stopped a bit short, so there isn’t as much to cover today, but one clear message came through. Think really carefully about the methods you make public. If you go down the road of opening up the entire class, you dangerously couple classes together. Your like is much more difficult down the road when you need to change a class when you have no idea which methods are in use.

Instead, choose the bare minimum to expose and hide as much as possible. That way, you may easily gut and re-implement the entirety of the private methods while preserving the same interface.

I find that Rails makes this particularly tough. By default, every model exposes getters and setters for all attributes. That’s really great in the world I come from, building simple marketing focused sites with a bit of app thrown in for good measure (to drive a CMS, email form, or simple CRM).

When it comes to developing a serious app with tons of models, associated libraries, and complexity galore…it can become quite challenging to keep everything clean and concise. I find that I rarely think in terms of the API a class provides. I can juggle the whole system (barely) in my head, so all classes generally know about whatever I feel like.

I was really blown away by this statement (in the context of describing the Law of Demeter), and have no idea whether this would be possible for me:

A method should not invoke methods on objects that are returned by any of the allowed functions. In other words, talk to friends, not to strangers.

Wow…how does one do that? The answer (which I don’t fully grasp) has to do with the authors distinction between objects and data structures (one being full of behavior, and the latter being just a container for data). It’s a pretty wild and interesting concept. I’m fascinated to see how I can apply it in the Ruby on Rails world.

Peeking ahead a bit, it seems that some of the answers I need may come later in the chapter.

Feeling like all this code structure talk is mamby-pamby? I don’t blame you. Head over to Miles blog for his introduction to a language that will put hair on your chest: Closure.

PPL: Day 8 – Horizontal formatting

2010-06-21T12:44:23Z

This is part of the Peer Pressure Learning 30 series. Go read my introduction to the experiment Miles and I embarked on.

Monday morning and I’m back on track. It’s barely 8:00am and I have my reading done.

Today’s reading: pg 85 – pg 92

This section on horizontal formatting really challenged some of my thoughts on code. As I said before, I’m a bit of a geek for formatting code a certain way. Uncle Bob (the author) isn’t as infatuated with the little “beauty” details as I sometimes am. I routinely line up assignment operators, hashrockets, or any other element that’s repeated on multiple lines. He points out some reasons not to do that, despite the visual appeal.

An example of my hyperactive horizontal alignment from the filtering Twitter Proxy I wrote:

A couple differences in his coding style that I want to ponder further:

You probably shouldn’t break indentation – When a block can be done on one line or indented over several, the author explains that he almost always (he of course, used Java) went back to the indented multi-line version. In the example below. the “return true” is the critical element, the thing that actually executes. That shouldn’t be hidden in the middle of the line. Rather, it’s indented and it’s scope is clearly shown. (Note: I did use the more Ruby-ish inline if statement. I felt that to be a reasonable breakage of standard indenting…but maybe it isn’t!)

Don’t necessarily line up similar elements – I find that I almost always line up like elements in named_scopes, routes, associations, etc. The author makes an interesting point that while you may be making the code more aesthetically pleasing, you can obscure relevant differences. The code becomes too easy to scan, allowing someone to miss critical elements of the code. The example below may be as stretch, but I could see someone missing the difference between the TRUE and FALSE. I guess one must weigh the value of showing how similar the two statements are with making their difference clear.

I’m interested to talk with my team about implementing some basic style guidelines. The text talks about a situation the author was in where they spend just 10 minutes making some decisions that affected the whole project. That tells me that it doesn’t have to be a long, drawn out affair.

What will get interesting for a web app project is that we have to integrate several different languages. I’m already finding that I have to tone down the amount of Ruby-specific stuff as we have to shift from Ruby to JS to HTML and each has its own common idioms. That’s what makes this fun!

PPL: Day 7 – Vertical formatting

2010-06-21T11:44:21Z

This is part of the Peer Pressure Learning 30 series. The introduction to the experiment post will make all things clear.

Once again, the weekend has almost been my undoing. I may have to accept that the weekend requires doing PPL at night before bed with weekdays sticking to the morning routine.

Today’s reading: pg 75 – pg 84

Chapter 5 kicks off discussions of code formatting, a topic I really enjoy. I’m a complete freak for making sure my hashrockets line up, there’s no whitespace at the end of a line of code, etc. I’d like to say that it’s because I have some specific value on professionalism or neatness, but that would be a load of crap. For whatever reason, I spot little inconsistencies and they drive me nuts…it’s probably a bit OCD because I’m sure that I blindly skip over the stupid stuff I do that others hate.

Clean Code has kept the discussion rather focused on the utilitarian side. Steve Smith‘s talk at the Great Lakes Ruby Bash on “Designing Code” takes the whole concept in a direction I love.

Designing code

View more presentations from Steve Smith.

The author gave some great suggestions about how to sort the methods within a class. I’ve always wondered about that as mine end up being a mish-mash, depending on when I added a method. He suggests that:

Methods are defined below the point where they’re first called
Like methods go together (they are logically or actually connected)

He also spends some time talking about proper whitespace, limiting files to a reasonable length (files over 500 lines may indicate a concept that’s too large for a single class), and keeping in mind that you’re in the business of communicating. I love this introduction to the chapter:

Code formatting is about communication, and communication is the professional developer’s first order of business. Perhaps you thought that “getting it working” was the first order of business for a professional developer. I hope by now, however, that this book has disabused you of that idea. The functionality that you create today has a good chance of changing in the next release, but the readability of your code will have a profound effect on all the changes that will ever be made. The coding style and readability set precedents that continue long after the original code has bee changed beyond recognition.

Good stuff.

PPL: Day 6 – Bad comments

2010-06-21T11:43:42Z

This is part of the Peer Pressure Learning 30 series. Jump to my introduction to the experiment if you got here from Google or some other site.

This is my first weekend PPL day and it almost broke me! It’s been a heavy week, so I was barely able to fall out of bed. Even then, it was 30 minutes later than usual and the kids were already going full steam. So here I am at 10:53pm because I really care a ton about this stuff. Thank goodness I got a Kindle copy of Clean Code as the paper one is collecting dust on my desk this weekend.

As a brief aside, I got a ton out of Gary V’s talk from RailsConf. I listened to it three times today. His push to make sure you do what really means something to you resonates a ton with me. Go watch it!

Enough rambling!

Today’s reading: pg 59 – 74

The section shares a rather long list of bad comment habits and styles. I couldn’t begin to do them justice. My thought is to share a few of the mistakes I’ve found myself making of late. Having jumped into my first group project (I never coded on anything with more than one full-time developer), I quickly got accustomed to writing comments. I didn’t do it at first, but our team lead quickly pointed out the damage that my sparse commenting would eventually cause. Now, about 6 months in, I think I’ve gone too far. I’m finding that I include header blocks on almost every method, no matter how obvious it’s purpose:

The worst thing I do (and I find that I do it in conversation, emails, and IM) is getting crazy wordy in comments. I’m so enthusiastic to explain what’s going on, why we implemented things the way we did, etc. that I’ve written small novels is a couple sections of code. Worst of all, they’re so long that it would be difficult to tech edit them later to make sure it’s all still accurate! Arg!

My goal for this week will be to cut the redundant/obvious comments. I’ll also look to use shorter, simple language when describing concepts. And when I find something that’s sufficiently complex to seemingly require a short book…I’ll see what can be done to simplify things. Wish me luck!

Take a moment (or save it into Instapaper…the most wonderful too ever) to read Miles’ Day 5 post on Scala!

PPL: Day 5 – Good comments

2010-06-18T13:02:14Z

This is part of the Peer Pressure Learning 30 series. Be sure to read my introduction to the experiment if this doesn’t make sense to you!

It’s Friday, and I’m a little apprehensive about PPL, heading into the weekend. I’ve made great progress this week, reading and blogging all week long. I need to keep the big mo going and stay on the wagon. Here’s my progress thus far (and yes, I counted the several days of ramp-up blogging…don’t judge me):

Today’s reading was on Comments. I made it through the first section on “Good comments”. I stopped my reading short before hitting the rather long “bad comments” heading.

Today’s reading: pg 53 – pg 59

If you’re a developer, I can’t recommend Clean Code enough. It’s been tremendous already. There were so many good points that jumped out to me, I don’t feel like I could do them justice by summarizing them. So instead, I want to quote some of my favorite lines:

If our programming languages were expressive enough, or if we had the talent to subtly wield those languages to express our intent, we would not need comments very much — perhaps not at all.
The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures.
Why am I so down on comments? Because they lie. Not always, and not intentionally, but too often. The older a comment is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong. The reason is simple. Programmers can’t realistically maintain them.
Truth can only be found in one place: the code.
Some comments are necessary or beneficial. Keep in mind, however, that the only truly good comment is the comment you found a way not to write.

I’m working on an OSS Twitter app that scores people’s level of annoying. I put together this code to cache a single user’s Twitter account details, only updating them (calling out to a slow API) every 24 hours. The #find_by_username runs the whole show. I love how crisp that method is now (it was a wreck 24 hours ago. The tests are all dirt simple now, it’s really great.

Coming on the heels of the previous chapter on writing small methods and this chapter on comments, I’m extremely proud of this class. It reads well and may not need any comments!

Here’s an earlier version (and if you can imagine…it was worse before this):

For more PPL fun, head over to Miles’ blog for his post on MongoDB.