On Writing Good Software

on December 22, 2007 @ 10:21 PM

The craft of writing is so similar to that of software development. I recently found this out by reading On Writing Well by William Zinsser. Below are some quotes from the book with commentary on how they apply to the software developer.

You will write only as well as you make yourself write.

Substitute write with write software and it remains a truism.

Writing software is easy. Writing good software is hard. It takes discipline to become a good software developer. The only way to get there is to write better software today then you wrote yesterday. And the only way to do that is to learn from what you and others have written.

Clutter is the disease of American writing.

The same can be said for writing good software. It’s very painful to create or find a bloated method or class doing something it shouldn’t be doing. It’s even more painful to maintain. Small and simple works wonders within the design of a program.

Strip every sentence to its cleanest components.

Strip every method and class to include only the functionality it needs to do its job. Methods which might be used at some point—get rid of them. Comments which try to explain away complexity or ambiguity—simplify the code so it’s readable and remove the them. Classes which try to do everything—refactor and pull out things it doesn’t need to do into their own class or module. Clever code—turn it into simple code. Simplify, simplify, simplify.

You must know what the essential tools are and what job they were designed to do.

A carpenter must know how-to hammer nails and saw wood before he can build a house. Likewise, a developer must know how-to write good code, perform object decomposition and refactor before he can build an application. Other basic tools and skills that a developer should know are: writing testable code, testing and test automation.

Take your stand with conviction.

Care about the software you develop. Stand up for customer involvement. Stand up for short iterations. Stand up for testing. Stand up for quality, even when the deadline is fast approaching, it’s the best chance you’ve got for hitting it with working software.

Never hesitate to imitate another writer.

Never hesitate to imitate another developer, especially one that writes better software than you. It will make you better in the process. Find open source projects that exceptional developers have worked on and read that code. How are they attacking a problem? How did they solve it?

A while back a coworker asked me if I had read through Mephisto’s source and I said I had scanned it, but that I didn’t think it was anything special besides the routing. A few weeks later I started reading the source. Rick Olson, the author of Mephisto, has some great techniques and code tucked away in Mephisto, things that I would be missing out on if my coworker would have never challenged me to read the source. Thanks Drew.

...it’s hard not to be intimidated by the expertise of the expert.

Ask questions. If you don’t understand something, ask. If you think it’s a dumb question, ask. Let the resident expert enlighten you. When they explain something and you still don’t get it, ask clarifying questions. They didn’t wake up one day an expert. And neither will you.

Writing is related to character. If your values are sound your writing will be sound.

Developers who have character are exceptional people to work with. They not only write better software, they inspire those around them to write better software.

Decide what you want to do. Then decide to do it. Then do it.

For all of those “I want to learn language X”, “I want to start learning TDD”, etc. statements—start learning language X, start doing TDD.

Think small.

Two immediate thoughts come to mind. First, good object decomposition. Work with simple objects that work with a single responsibility and let the overall system evolve of those simple objects. Second, short iterations over long ones and short stories over full blown specification documents. Thinking small in these regards will help you produce cleaner and simpler code as well as produce the right working features—sooner.

rak, ack and findit

on December 13, 2007 @ 04:52 AM

In Helpful Command Line Tools from last month I posted on my custom findit script.

Jason Porrit commented on that post and mentioned ack , a perl alternative to grep and find which offers terminal color highlighting to your results. I also found this morning a ruby alternative called rak

All of these utilities do the same thing, they search a directory structure for files whose contents match a given pattern.

Here’s Ack

Here’s Rak

Here’s findit

Overall ack and rak beat out findit, but findit has a much better name. I think I’ll just alias findit to rak. (yes I”m biased to ruby code over perl code).

The only thing ack and rak are missing is a filename only option. If I can find every file matching a pattern from a given start directory that would rid me of findfile as well!

Helpful Command Line Tools

on November 23, 2007 @ 02:54 PM

Here’s a post about some of the command line tools (both standard on *nix systems and homegrown) which make software development just a little more efficient.

The homegrown tools may only work on OSX. This is because unix utilities on OSX often have different options to do the same thing (such as sed’s -E on OSX and -r in Ubuntu).

find

find is a unix utility for searching files in a directory hierarchy. find is a powerful tool that comes with a lot of options. Some are more common then others.

Here are the options I use frequently:

• -name pattern – this will match filenames against the supplied pattern
• -exec command argument \; – runs the specified command against each file matched

1
2
3
4
5

# Using -name to find all files or directories which match the pattern "*.rhtml"
find ./ -name "*.rhtml"

# Using -exec to find all rhtml files whose file contents match "Continuous Thinking"
find ./ -name "*.rhtml" -exec grep -Hn "Continuous Thinking" {} \;

For development the -name option doesn’t help me much as TextMate’s Apple-Tab is far superior and faster to use, but editors like TextMate lack the efficiency of doing a -name and -exec combination from the command line. Sure TextMate has Apple-Shift-F to search file contents project wide, but what about all of those files you want to exclude (like log files), plugins (vendor/plugins) or the whole rails directory (vendor/rails).

TextMate doees give you the ability to exclude certain files (or directories) from your TextMate project, but it removes all references to them from within your TextMate project. This feature will speed up Apple-Shift-F searches, but sometimes you want to include those other files or directories.

The find command given the -name and -exec options can be a pain to type out. So I’ve written a helper script called findit.

findit

findit is a wrapper around find. It’s simple and fast. It’s usage is simple:

• findit where pattern

Maybe you’re looking for that view template which contains the text ‘Fuzzy Bear’:

1
2

zdennis@elijah:> findit app/views/ Fuzzy Bear
app/views//bears/new.rhtml:26:      <label for="fuzzy_bear">Fuzzy Bear</label>

Notice how you don’t have to use quotations around the arguments Fuzzy Bear. Everything after the first argument is treated as a part of the pattern.

Another example may be that you’re looking for where alias_method_chain is defined in rails. Well let’s look:

1
2

zdennis@elijah:> findit vendor/rails/ def alias_method_chain
vendor/rails//activesupport/lib/active_support/core_ext/module/aliasing.rb:23:  def alias_method_chain(target, feature)

So the power of findit comes from the fact that it’s easy to use and it handles most common occurrences of what a developer like me looks for such as the filenames that matched, the line numbers it matched on and a printout of those matching lines.

findit also ignores all .svn, CVS, .log, .project, .dylib and .o files. Of course you can change this though by editing the findit.

Download

Give it a try click here

findfile

findfile is similar to findit except that it only matches on filename patterns. The usage is still the same:

• findfile where pattern

Recently I had some issues with installing PostgreSQL from ports and there was a patch to the Portfile for the PostgreSQL port to get it to install correctly. I had no idea where the Portfile was so I let findfile to the work:

findfile /opt/local/var/macports Portfile | grep -i postgres

Download

Give it a try click here

locate | slocate

locate (and by extension slocate) may be one of the most under utilized unix tools in the mac world.

locate is used to find files by searching a database. Since it uses a database of file paths it is almost instantaneous whereas tools like find can take a while depending on how much files you have in a directory structure.

slocate can be thought of as “secure locate”. For more information consult this doc

Here’s the same example from findfile but this time using locate:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

locate Portfile | grep postgres
/opt/local/var/macports/sources/rsync.macports.org/release/ports/databases/postgresql7/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/databases/postgresql80/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/databases/postgresql80-doc/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/databases/postgresql80-server/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/databases/postgresql81/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/databases/postgresql81-doc/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/databases/postgresql81-server/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/databases/postgresql82/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/databases/postgresql82-doc/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/databases/postgresql82-server/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/databases/postgresql83/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/databases/postgresql83-doc/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/databases/postgresql83-server/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/databases/postgresql_autodoc/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/java/postgresql-jdbc/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/python/py-postgresql-exception/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/python/py-postgresql-greentrunk/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/python/py-postgresql-layout/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/python/py-postgresql-pqueue/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/python/py-postgresql-proboscis/Portfile
/opt/local/var/macports/sources/rsync.macports.org/release/ports/ruby/rb-postgres/Portfile

locate loses its usefulness when it’s database is out of date. Fortunately it’s easy to add it to cron. Here’s what I have in my /etc/crontab file to have slocate update it’s database every night at midnight:

0 0 * * * root /opt/local/bin/slocate -u

locate comes with Leopard, and slocate comes with ports. I have my locate aliased to actually run slocate. They use different databases so pick one and use it or alias one command over the other like I have. There’s not much of a point to have both slocate and locate.

If you decide to give slocate a try you can install easily by running:

sudo port install slocate

whatsmyip

whatsmyip is a script I use in my screen configuration so I can always tell what my local ip address is. ifconfig output is pain enough to look at and I try to avoid it at all costs:

1
2

zdennis@elijah:> whatsmyip 
en1: 10.0.4.100 en2: 10.37.129.2 en3: 10.211.55.2

Download

Give it a shot, click here

Programmer, Developer

on June 13, 2007 @ 03:16 AM

I used to think that I was a software developer based on the sole fact that I was paid to write code, no matter how crappy it was. Over the past few years I’ve realized that I was no more of a software developer as a guy who picks up trash on a construction site is a contractor.

I’ve noticed that alot of so called “developers” fall into the same camp that I was in. I’ve mentally made a distinction between a Programmer and a Developer. _This is much more generic dictinction of different types of coders then say an Apprentice, Journeyman or Craftsman is._

A Programmer is someone who codes. They don’t necessarily take into consideration a whole lot of things outside of fact of getting the job done.

A Developer is someone who codes with consideration. They consider:

• coding quality and best practices
• program design with natural decomposition
• testability, automated testing, manual testing
• readibility
• maintainability
• refactoring
• code performance (when its time to evaluate performance)
• teamwork
• responsibility to their customer and to their fellow teammate(s)

These definitions are influenced from object-oriented thinking and agile software development practices. You may completely disagree with them entirely. I’ve raised the bar for how I develop software. If it’s less for you then we just have different expectations of what makes a Developer. I’m ok with that. But, is your customer?

Ever since I started writing code I recognized that my potential was where I wanted to be. I could see the potential of what I could become and what I could accomplish. With this I had a genuine thirst for knowledge and I was eager to quench it. I’ve spent thousands of dollars and have read tens of thousands of pages from technical books. I’ve spent countless hours coding.

I spent too long of a time in the Programmer camp. I could have been much farther ahead early on given a few degrees change in direction.

So what was my problem? My problem had to do with the following goals when I first started:

• knowledge of multiple programming languages
• knowledge of different types of development: web apps, cgi, standalone,daemons, libraries
• coding speed
• all previous items as soon as possible

I wanted to know as much as possible in as little time as possible and I wanted to be able to produce results as fast as possible. A worthy goal, but the goals fell short of what is required of a software Developer.

When you learn as much as possible in the shortest amount of time with no regard to how you take that information and you end up learning only a small amount of what was there to be learned.

When you apply what you’ve learned as fast as possible with no regard to any of the aforementioned Developer “considerations” you end up making habits out of bad practices. And it will take alot of time and discipline to break them.

Developers take on a personal responsibility for the software they write. They don’t just value the end result. They value the entire process leading up to the end result and then they value the end result.

While Programmers continually apply bad practices, Developers provide consistently good practices. From what I’ve seen it goes like the following:

• while Programmers avoid testing to produce faster short-term, Developers continue test to produce faster and more consistently long-term

• while Programmers copy and paste over and over again to produce faster short-term, Developers refactor and create re-usable components to produce less buggy software, faster, long-term

• while Programmers avoid the use of decomposition because everything can be inlined to produce faster short-term, Developers use decomposition to provide a solution which makes more natural sense (this leads to more manageable, maintainable, readable and scalable code for the long-term)

• while Programmers often code by themselves to produce faster short-term, Developers value the input and ideas generated from other people to produce better and more correct solutions (this often leads to avoiding common mistakes from not correctly understanding the problem description and solution requirements)

• while Programmers often code 12+ hours several days in a row to produce more in a shorter amount of time, Developers work a sustainable-pace to produce more correct code in a shorter amount of time (when you’re brain is tired and you are tired you make mistakes, if you keep on coding you just dig yourself a bigger hole. Staying fresh with a sustainable pace minimizes this.)

• while Programmers commit to unrealistic customer expectations immediately, Developers communicate why the expectation is unrealistic and work with the customer on determining a realistic set of features in a realistic amount of time.

This isn’t to say that Programmers are evil coders. The term “Programmer” encompasses alot of people. These people might be:

• inexperienced,
• irresponsible,
• lacking discipline,
• or just bad programmers

Every coder starts out in the Programmer camp. Whether they evolve to the Developer camp is simply up to them. Who determines whether they’re out of the Programmer camp? They do.

Responsible Programmers quickly evolve into effective Developers because responsibility requires discipline and discipline does the right thing in any circumstance. The sooner you take responsibility for your craft as a software developer, the sooner you’ll enjoy the benefits of being a Developer.

Communication is essential

on April 12, 2007 @ 01:32 AM

Models [charts, diagrams, stories, graphs, etc] are valuable only to the extent that they facilitate communication among human beings. —David West

Communication is the most essential part of a project. Sometimes the artifacts that are generated to help facilitate communication end up hindering it. If the target audience can’t understand the artifacts you’re presenting them with chances are you need to stop trying to explain it to them and find something that they can understand.

the effort required to construct the model must be less than the communication value that arises from its user. —David West

I was once the project lead on a web-based project management application for a Fortune 50 company. The GANTT chart was deemed by the customer to be the most effective form of communication since everyone else in his company used them. In fact, they all used Microsoft Project to generate them.

We spent about six weeks of development per the customer’s direction integrating support to output an exact Microsoft Project GANTT chart replica. At the end of those six weeks the GANNT chart was canceled.

I don’t know why the GANTT chart was canceled for sure, but during the time of development we discovered that our domain experts and our customers didn’t really understand a GANTT chart. They sorta knew what it looked like because it was what they gave to their coworkers and bosses every few weeks to report progress, but they didn’t really understand what they were really trying to capture.

I think that once they understood what they actually wanted and what a GANTT chart actually was that it didn’t make sense to use a GANTT chart after all. But that’s just my speculation of course.

Tools like Microsoft Project are evil, mostly

I don’t like tools like Microsoft Project or any tool that locks you into their process for how you should do things. Or maybe it’s that I don’t like people who use tools but don’t understand how to use the tool or at least what the outputted artifacts (diagrams, GANTT charts, etc).

Thank you to people who don’t effectively communicate

I try to communicate effectively, and I try to constantly improve that communication. People who don’t either of these things will make my portfolio bigger.

Recapping UI Architectural Patterns

on March 04, 2007 @ 05:39 AM

Here are some recent summarizations and thoughts on classic classic Model View Controller , Model View Presenter and then finally end on the more recent Presenter First pattern.

Model View Controller

Model View Controller (MVC) is an architectural pattern used to separate domain objects which model our perception of the real world and the presentation objects used which are the GUI components that we see on the screen.

• domain objects should be completely self contained and they should work entirely without reference to the presentation.
• domain objects should support multiple presentations, possibly simultaneously
• domain objects send events when it’s state changes to allow views and controllers to observe those events

In MVC, the domain element is referred to as the model. Domain objects are to represent their real world counterpart. For example, a domain object for a person would be a Person object.

• the controller’s job is to take user input and figure out what to do with it
• the view’s job is to be the UI (The view should contain as little to no logic as possible.)

There is a model-view-controller for each element on the screen.

• the model object does not contain a reference to the controller or the view
• the controller and the view contain a reference to the model
• the controller and the view do not contain references to one another
• the controller and the view observe the model object for events/changes

The design of MVC shows that the controller does not directly update the view. Instead it notifies the model, and lets the observer mechanism take over. Since the view is observing the model object it should update itself accordingly.

Issues With MVC

Issue #1 – View Coupling

• having one view update another view couples the views
• you can solve this by creating a new view which is composed of the previous two views

Issue #2 – View Logic

A second issue which is a variant of the first issue exists when an update in one view propagates a change to itself or another view which is based on criteria based on the change in the domain object.

The problem with the second issue is that you have logic that makes a decision about the presentation of your model. The logic to do this isn’t necessarily domain logic so it doesn’t belong in the model. You also don’t want to put unnecessary logic in the view.

• creating a new model object that is oriented around the screen (presentation) which wraps the original model object. The view logic could go in this model object without affecting the original model object. (this would be equivalent to creating an intermediate Presentation Model object to handle the view logic)

According to Fowler, the Presentation Model also allows you solve the issue of presentation state, as well as presentation logic. By wrapping the domain model in a presentation model you can maintain view specific logic and state separate from our domain logic. All the while leaving the view very clean.

Issue #3 – View Testability

Testing views is extremely difficult. This is one of the reasons why MVC suggests to leave views as simple as possible, because they are hard to test.

You can reduce the risk of issues in the view by moving most, if not all of the logic outside of the views into domain objects or presentation model objects which can be self-contained and are easier to test.

Conclusion

MVC is the building blocks for breaking out domain logic from presentation logic.

Testing a strict MVC architecture seems to have its drawbacks especially if complex view logic is kept in the view. The overhead of creating a model/view/controller for each UI element also seems to be a daunting task to coordinate and test.

Rather then strictly following MVC it seems to be a better approach to utilize a MVP approach.

Links

• http://en.wikipedia.org/wiki/Model-view-controller
• http://www.martinfowler.com/eaaDev/uiArchs.htm

Model View Presenter

Model View Presenter (MVP) is a architectural pattern similar to MVC. Whereas in MVC there is a controller/view for each UI element, in MVP there is a typically a single presenter/view for each for screen or at the least for each set of complex screen elements.

MVP and MVC share the commonality that they both rely on the observer synchronization. In MVP the presenter handles user actions and updates the model. In MVC the controller handles user actions and updates the model. In both MVP and MVC the view will then be updated by observing events/changes on the model.

• one variation maintains the same relationship between the model, view and presenter that is maintained through MVC’s relationship of the model, view and controller.
• a second variation allows the presenter to have access to the view to update the view when complex view logic is required, otherwise view logic would go in the view. Fowler refers to this as the Supervising Controller (aka Supervising Presenter).
• a third variation puts all of the view updates inside of the presenter. This implements what Fowler refers to as a Passive View.
• a fourth variation of this is implemented in the Presenter First pattern. (this will be describe later)

Conclusion

MVP simplifies complex view updates by utilizing a Supervising Controller. By extracting out complex view logic is promotes greater testability for your application.

Allowing a presenter object to handle the user actions for a screen, form or set of UI elements seems to cut down on unnecessary complication and overuse of observers as you could get with MVC.

Links

Links

• http://www.martinfowler.com/eaaDev/uiArchs.htm

Presenter First

The Presenter First (PF) approach is a variant of MVP. In practice the authors emphasize using it in an agile development process which build features into an application given customer stories. It is considered to be a hybrid of process and pattern.

• separation of business logic and view logic
• separation of complex view logic from the view
• decoupling of the view from the presenter/model
• provide fully testable GUI applications

PF works by composing the model and the view into the presenter via dependency injection. The presenter is created, but is never reference throughout the application. It simply glues together the model and view.

The model nor the view contain a reference to the presenter. Instead they send events that the presenter observes, and the presenter then coordinates those events and updates the model or view accordingly.

View —> Presenter <— Model

PF states that the view is the most complex, tedious and time consuming component to test. PF’s goal is to leave the view as simple as possible. One way it promotes to do this is to only allow your view to manage simple data types. If complex data types are handled in your view, then your view must contain the ability to process and correctly display the complex data types. Since this promotes additional logic in your view, PF discourages this.

PF ties user stories directly to a specific MVP triplet. The term “triplet” is used to refer to an instance of a model, view and presenter. Triplet is commonly referred to as a “triad”.

PF takes into account that complex view logic that exists. Often times that logic is mixed in with the domain objects. The problem with this is that the domain objects now contains a mixture of domain logic and view logic. This makes the code harder to read and it complicates the interaction between the model, presenter and view because complex view updates are propagating from the model itself.

PF solves this by introducing an “adapter” object. The adapter object goes in between the view and the presenter. The presenter will now reference the adapter, and the adapter will reference the view. There now exists a place that isolates any logic that is needed for the view. View logic is now fully testable.

Also, the adapter object may lead to an adapter-model object in which only the adapter would reference. This could be used to maintain view/presentation state. Even if an adapter object is introduced, the term “triplet” is still used.

PF also suggests that the presenter objects have no public methods and that they are stateless. The presenter’s job is merely to coordinate events between the view and the model (or vise versa).

PF also suggests that starting with the presenter first is the best place to start the development of a user story. Over time PF suggests it is less expensive to start with the presenter, rather then the view or the model.

Links

• http://atomicobject.com/pages/Presenter+First

Conclusion

Presenter First promotes a consistent, predictable convention for class naming, and object responsibility. It allows for IDEs or development tools to be created to speed up the development, creation and testing of these objects.

The interaction between the components in PF is easy to understand and the way that it is approached by the authors seems to remove issues with more classic MVC patterns or other MVP variants.

COBOL, A Short Visit

on December 06, 2006 @ 04:58 AM

I wrote some COBOL today. I can’t say it was fun, enjoyable or even breath taking. It was more of a “oh my gosh, I’m so glad we have languages better COBOL these days!”.

I was working with a vendor who runs a data extract program from a COBOL program. We needed to utilize a non-printable whitespace character as a field delimiter. They didn’t know how to do that since COBOL treats all whitespace equally, as spaces. I was hoping COBOL would treat \t literals as actual tabs, but it doesn’t.

So I ended up with my sample program:

1
2
3
4
5
6

000100 IDENTIFICATION DIVISION.
000200 PROGRAM-ID. hello.
000300 PROCEDURE DIVISION.
000400 DISPLAY X'09'.
000500 DISPLAY "Hello World!".
000600 STOP RUN.

That X’09’ gave me my binary character for a tab! I can’t say I’d want to program in COBOL, but for a very short visit it was fun to read up on it, and write some sample programs. The above six-liner just happened to be the one I needed.