carriagereturn.org

architecture

Mon, 20 Jul 2009 04:10:06 -0000

*Layers*

Well-architected systems tend to be organized in multiple layers depending only on 'lower' layers. The lower layers contain generic functions that are used by the more specific functions in the upper layers. Forcing one-way dependencies between upper and lower layers avoids circular dependencies between components. It also clarifies the process of unit and integration testing: Test the lower levels first and build up. The higher levels can be tested with mocks / stubs replacing the lower layers.

design

Fri, 17 Jul 2009 04:10:06 -0000

Think like the user:

It takes a lot more work to understand the other person than it takes to understand you.

You might say, "I have these two things together so I will let the user (the person using the API) manipulate them." But that user didn't say, "Hey, I want to manipulate these two data structures!" Often the user is saying, "I want to get this result." If users could get a result without manipulating the data structures, they'd be happy as clams.
If you can make it more natural for them to get that result, the fact that you have to go through 10 times as much work to access those data structures is good; it means you are providing value. Many people are much more likely to think about what they have in hand and what they can do. They think from the implementation out, instead of thinking from the user in.

unit testing

Thu, 16 Jul 2009 04:10:01 -0000

Unit Testing:

We want to eliminate outside dependencies as much as possible when testing a single component in isolation.

Use Stubs and Mock objects to build a harness around the component. Working test first, and designing our components to be testable in isolation significantly reduces their coupling with each other. Tests are first class clients of the code, so the code often changes in response to the requirements of the tests. The tests are the first client of the code, the second is usually the application, and if re-used there can be many other clients.

See DependencyInversionPrinciple

Testing at the unit level ensures that when integration begins we can have confidence in the functinality of each component being integrated.

Always test each application with xUnit (http://www.junit.org), whether it is part of a bigger system, or standalone.

design smell

Wed, 15 Jul 2009 04:10:05 -0000

Symptoms of a bad architecture / rotting design:

*Rigidity*

Rigidity is the tendency for software to be difficult to change even in simple ways. Every change causes a cascade of subsequent changes in dependent modules. What begins as a simple two day change to one module grows into a multi-week marathon of change in module after module as engineers chase the thread of the change through the application.

*Fragility*

Fragility if the tendency of software to break in many places every time it is changed. Often the breakage occurs in areas that have no conceptual relationship with the area that was changed.

*Immobility*

Immobility is the inability to reuse software from other projects or from parts of the same project. It often happens that one engineer will discover that he needs a module that is similar to one that another engineer wrote. However it also often happens that the module in question has too much baggage that it depends on.

*Viscosity*

When faced with a change, engineers usually find more than one way to make the change. Some of the ways preserve the design, others do not (i.e. they are hacks). When the design preserving methods are harder to emply than the hacks, then the viscosity of the design is high. It is easy to do the wrong thing but hard to do the right thing.

general principles

Tue, 14 Jul 2009 04:10:05 -0000

Programming is about communication between humans with a computer eavsdropping. There is a tension between communicating to the machine and to other programmers with the same source text.

general principles

Mon, 13 Jul 2009 04:10:05 -0000

From Dave Hoover, a quote from C.S. Lewis:

If we let ourselves, we shall always be waiting for some distraction or other to end before we can really get down to our work. The only people who achieve much are those who want knowledge so badly that they seek it while the conditions are still unfavourable. Favourable conditions never come.

general principles

Fri, 10 Jul 2009 04:10:05 -0000

Any intelligent fool can make things bigger, more complex, and more violent. It takes a touch of genius, and a lot of courage, to move in the opposite direction.
---Albert Einstein

team

Thu, 09 Jul 2009 04:10:05 -0000

"If you want to build a ship, don't drum up the men to gather wood, divide the work and give orders. Instead, teach them to yearn for the vast and endless sea."

- Antoine de Saint-Exupéry (attributed)

There are a lot of ways to build bad engineering teams, and very few ways to build great ones. I've come to believe that the attributed quote above spells out pretty much the only way I know how to build a great development group.

The best way to get developers to build something great is to make them believe your goal is worthwhile. If you do, control from the top will not only be unnecessary; it will be impossible. That's the best situation you can hope to create, and frankly I love that so many people don't believe that, since it makes things so much easier for those of us who do.

general principles

Wed, 08 Jul 2009 04:10:05 -0000

Less is more.

exception handling

Tue, 07 Jul 2009 04:10:03 -0000

*Do Or Die*

Do-or-die is simple: either an operation succeeds or it raises an exception. When you call a do-or-die method, any normal code path relying on the results of that method have a guarantee for sanity - there are no problems to check for or deal with in the normal code path. The abnormal code path coping with the raised exception handles all problems. (Contrast this with languages lacking exceptions.) This means:

1. Any procedure always returns void; no boolean returns that require checking for success or failure. Just call the procedure and be done with it.
2. Any function always returns a valid object; no null returns that require nullity checks. Just capture the return and use it as expected.

exception design

Mon, 06 Jul 2009 04:10:05 -0000

*Designing with exceptions*

Think what the throws clause should contain at the abstract contract level.

Exception translation can be helpfull, for example if in something that reads a database deep inside it could cause a MalformedURLException - the interface should not have to deal with that, hence exceptions can be wrapped in more meaningfull ones.

exception handling

Fri, 03 Jul 2009 04:10:05 -0000

*James Gosling on localised exception handling* (paraphrased occasionaly):

When you try to open a file and it's not there, your coping strategy is really determined by what you were going for. Some guy (i.e. piece of code) miles away isn't going to know what to do. The code that tried to open the file knows what to do, whether it be trying a backup file, looking in a different directory, or asking the user for another filename.

Having one big catch clause on the outside really only works if your exception handling philosophy is simply to die. If you have an event loop, you can maybe cause that one event to just be tossed. If you have a plugin architecture, the enclosing environment could respond to a failure in the plugin by disabling it. But if you're not doing an event driven program or plugins, there isn't an outside place where you can take big hunks of functionality and saw them off.

It's good to have a last ditch catch clause though, specifially for a server, so that we can fail the offending request only.

In general, when you are writing a declaration in a throws clause, it is good to try to be as specific as possible because it gives more information to the context about exactly what went wrong.

testing tdd

Thu, 02 Jul 2009 04:10:11 -0000

*Test Driven Development*

Test First Development (or Test Driven Development) implies that rather than deferring testing until the end of the project we move it to the beginning of the lifecycle. Before devlelopers code a new piece of functionality they define and develop the test cases describing the required functionality. Then, they develop code modules until all test cases succeed. Development occurs in rapid iteration cycles between developing, verifying and correcting code.

Automated testing, particularly as part of TDD, has the ability to change the dynamics of the development team in a way that testing is no longer seen as a burden but becomes a natural part of the development process. This change in developer mindset is key to test-driven development.

testing

Wed, 01 Jul 2009 04:10:03 -0000

How to investigate intermittent problems: http://blackbox.cs.fit.edu/blog/james/archives/000197.html

testing

Tue, 30 Jun 2009 04:10:03 -0000

To test you need to be able to:

- Control the system under test: Ideally via an API that allows control of the system (a test interface), or via a gui testing tool. API is much better.
- Inspect the results: Again an API is most helpfull but also good logs and consistent error reporting help.