Code Folder Structure

Posted on 2011/10/22 by Mathias Verraes

All code bases I ever read or worked with, share a similar folder structure:

  • Controllers
    • BlogPostController
    • CommentController
  • Models
    • BlogPostModel
    • CommentModel
  • Views
    • BlogPostsView
    • BlogPostDetailView
  • Helpers
    • …

The ones where the developer has read Domain Driven Design, or is using Doctrine2 or Hibernate, usually have a better focus on the domain model:

  • Model
    • Entities
      • BlogPost
      • Comment
      • User
    • Repositories
      • BlogPostRepository
      • CommentRepository
      • UserRepository
    • Services
      • UserService
      • …

The philosophy of these folder structures is usually inspired by the frameworks they use. After all, if your framework is organized like this, it must be a best practice, right? It does make really good sense for a framework to be organized in packages [modules, components, …] like this.

For your application, it’s a missed opportunity. You are not communicating the role each class has in relation to others, or the dependencies it has. A BlogPostRepository and a CommentRepository have no direct relation to each other, apart from the fact that they are both Repositories. However, a BlogPostRepository has a very tight dependency on BlogPost.

  • BlogDomain
    • BlogPost
      • BlogPost
      • BlogPostRepository
    • Comment
      • Comment
      • CommentRepository
  • CoreDomain
    • User
      • User
      • UserRepository

This makes it a lot easier to communicate bounded contexts, and to illustrate dependencies. For example, the BlogDomain depends on the CoreDomain. On a smaller scale, the BlogPost package depends on the Comment package. Zooming in even further, BlogPostRepository depends on BlogPost.

 

In other words: A BlogPost and a Comment know about their author. A BlogPost has zero or more Comments, but the Comments are not aware that they belong to BlogPost. A BlogPostRepository manages BlogPost entities, but those entities have no idea that they are being managed.

Obviously the whole example is too simple, as examples usually are. The point is that, to keep code clean, it’s important to think hard about coupling between elements. A folder structure aides to delineate depedencies. Close proximity in the tree suggests closer coupling. Documentation can further help to explain the direction of the coupling. We may just as well decide that Comments do know about the BlogPost they belong too, but that should be a conscious decision.

Posted in Software development | Tagged | 1 Comment

Coping with Change in Software Development

Posted on 2011/07/21 by Mathias Verraes

In a discussion about keeping developers motivated, someone said:

“I also try as hard as I can to isolate our developers [...] from out-of-spec change requests”

Sticking to the plan sure allows developers and managers to stay in their comfort zone. The project keeps moving forward, the deadlines are met. But we’re not in the business of meeting deadlines. We’re in the business of building software that delivers value to customers. As the customer gains new insight in what will get the most value, the specs change. And change they will.

The reaction of the software industry has traditionally been to avoid change. Get the customer to sign off on the plan, then stick to it. Make them understand that changes are going to cost them dearly. Shield the developers from change.

The effect is backwards: customers, managers and developers are instilled with a holy fear of change. When, after much resistance, a change becomes inevitable, nobody knows how to deal with it.

Knowing how to cope with change in a software project is a skill like any other, whether it’s atomic refactoring, or big architectural changes, or writing the automated tests that will help you keep your sanity in the process.

Like any skill, you can master it with study and practice. Perhaps the best way to learn how to cope with change in software development, is to deliberately introduce change. It would make an interesting experiment: tell your developers to change things, just to keep them alert and well-trained in the art of change. I don’t know if they will declare you crazy, or if they will be motivated by it. All I know is that I would.

Posted in Software development | Tagged , , | Leave a comment

Lazy Loading in PHP with Closures

Posted on 2011/05/17 by Mathias Verraes

Closures are a great way to do all kinds of neat tricks in PHP, and they’re particularly useful for Lazy Loading. I’m currently involved in a +200k SLoC legacy project, and the challenge is moving it to a Domain Driven implementation (while improving the performance), with the ultimate goal of making it more testable.

The problem

We want to find a Customer, and ask it for a list of Orders:


With the ActiveRecord pattern, this is simple. The Customer object holds an instance of the database adapter, and queries it for related Orders:

The downside of ActiveRecord, is that it violates the principle of Separation of Concerns. The Customer class contains domain knowledge (“What is a customer, how does it behave?”), as well as persistence knowledge (“How do we store a customer?”). The Customer class in our example even knows how to find it’s Orders in the database. The tight coupling between Customer and the database makes it less portable, and hard to test. Continue reading →

Posted in Software development | Tagged , , | 6 Comments

Ubiquitous Language

Posted on 2011/05/12 by Mathias Verraes

Customers usually have never been forced to really think about their domain in a structured way — let alone explain it in detail to a developer, who doesn’t know anything about that domain. Often the customer doesn’t have a set of clear definitions for the concepts his business uses daily, or has multiple terms for the same concepts.

Developers are even worse. They also tend to have vague concepts and lots of ways to name the same thing. Depending on where you look in the code or the documentation (if any), you might see: “bank account”, “account”, “bank_account”, “bankAccount”, “BankAccount”. And worse: “BA”, “bank_acc”, “acnt”. When storage is involved, you’ll find “item”, “row”, “record”, “model”. And another set of words for a collection of bank accounts: “list”, “array”, “collection”, “bankaccounts”, “acntset”, … you get the picture.

Even on small projects, this hinders communication. Developers, project managers, customers, and others involved with the project, need to communicate about the domain, but everybody uses a different, but equally vague terminology. Continue reading →

Posted in Software development | Tagged , | Leave a comment

Beautiful code

Posted on 2011/04/05 by Mathias Verraes

Jenkins/Hudson, the tool that has helped so many teams write better software, turns out to be rather ugly. And Santa is a fat drunk guy in a suit.

Code doesn’t have to be beautiful. Some of the most successful projects have the ugliest code. Marketing, features, vendor lock-in, shiny GUI’s and all kinds of real or imagined qualities are what make or break a software product. Of all the factors that’ll make you reach your audience, beautiful code dangles somewhere at the bottom. The business value of beautiful code is near zero. CEO’s, managers, customers, and users, they don’t give a shit about the code. So neither should we. Just keep pumping out those LOC’s. Continue reading →

Posted in Software development | Tagged | Leave a comment

Representing Money in PHP, Fowler-style

Posted on 2011/04/04 by Mathias Verraes

Whenever working with values in object oriented programming, it’s often a good idea to wrap them in a ValueObject. Money is a perfect candidate for a ValueObject: When talking about money, numbers are meaningless if they are not combined with a currency.

I’ve been using a very simple version of the Money pattern as described in Martin Fowler’s PoEAA. I couldn’t find a PHP implementation anywhere, so I decided to make my own little open source library for it. You can find it on my GitHub account (where else?).

Immutability

An important aspect of ValueObjects is their immutability: Continue reading →

Posted in Software development | Tagged , , | Leave a comment

Random thoughts on using Git

Posted on 2011/03/29 by Mathias Verraes

A couple of weeks ago, I switched from Subversion to Git for a couple of smaller projects. Below are some of my findings.

Switching from Subversion

Git is a little harder to understand than Subversion, because of it’s lack of a centralized repository, and because it has more concepts you need to understand. But if you already understand SVN well, it’s very manageable. I’ve no idea how the learning curve compares to SVN for a complete newbie to version control.

If you are on the fence, there are two things that I wish I knew about sooner: Continue reading →

Posted in Software development | Tagged , | Leave a comment

Accessing private properties from other instances

Posted on 2011/03/24 by Mathias Verraes

In PHP, when a property or method is marked private, it can only be accessed from within that class. That includes other instances of the same class. This may seem counter-intuitive at first, because we are used to dealing with instances of classes. The visibility operator however works not on object-level, but on class level.

An example: Continue reading →

Posted in Software development | Tagged , | 3 Comments

Keep your controllers thin with Doctrine2

Posted on 2011/03/23 by Mathias Verraes

Doctrine2 does such a nice job abstracting everything related to the database, that you might be tempted to do everything else in your controllers. Say we have a Bug entity:

To get a list of fixed bugs, we get the Bug repository from the EntityManager and ask for a list of Bugs where status equals ‘fixed’.

That’s easy enough. Surely there can be no harm in having this code inside a controller? Although this code doesn’t look like one, it is in a fact a database query. It’s a shortcut for this:

Having a query in our controller should ring some serious alarm bells. It means that despite all abstraction Doctrine2 provides, we are at this point still coupling the controller to the database. If one day we decide to change how bug status is represented in the database, we’d need to modify all our controllers.

Continue reading →

Posted in Software development | Tagged , | 4 Comments

Interface discovery with PHPUnit’s Mock objects

Posted on 2011/03/21 by Mathias Verraes

PHPUnit provides some great features to create mock objects. The idea is that when you are testing code that depends on another class, you provide the object with a mock instance of that class, instead of a real object. That way, you are making sure that your test will only fail if the system under test is broken, and not if one of it’s dependencies is broken. You could simply write a mock class and instantiate it, but PHPUnit can generate them for you.

The PHPUnit documentation doesn’t explicitly state this, but you can also create mock objects from interfaces. This makes a lot of sense if you think about it. In many cases, you should actually use mocked interfaces in your tests instead of mocked concrete classes. After all, the interface is the contract by which classes agree to talk to the outside world. Continue reading →

Posted in Software development | Tagged , | Leave a comment