A collection of more than 250 articles about Software Design & Development Best Practices.
With code samples for PHP/Symfony and Fortran applications.
The release of Object Design Style Guide
Today Manning released my latest book! It’s called “Object Design Style Guide”.
In November 2018 I started working on this book. The idea for it came from a conversation I had with the friendly folks at Akeneo (Nantes) earlier that year. It turned out that, after days of high level training on web application architecture and Domain-Driven Design, there was a need for some kind of manual for low level object-oriented programming. Not as low level as the kind of programming advice people usually refer to as clean code, but general programming rules for different kinds of objects. For instance:
Defining a custom filter and sorter for Sculpin content types
This blog runs on Sculpin, a static site generator. The generator itself runs on Symfony, which for me makes it easy to extend. However, I find that if you want something special, it can usually be done, but it may take several hours to get it right. In the end though, the solution is often quite elegant.
A custom content type for events
One custom feature I wanted for this website was a list of events (conference talks, trainings, etc.). Sculpin’s documentation suggests using a custom content type for that. This allows you to create a directory with files, each of which will be considered an “event”.
Improvements in personal website deployment
I wanted to be able to deploy MailComments to my Digital Ocean droplet (VPS) easily and without thinking. Due to a lack of maintenance, some more “operations” work had piled up as well:
- The Digital Ocean monitoring agent had to be upgraded, but
aptdidn’t have enough memory to do that on this old, small droplet. - The Ubuntu version running on that droplet was also a bit old by now.
- The easiest thing to do was to just create a new droplet and prepare it for deploying my personal websites.
- Unfortunately, my DNS setup was completely tied to the IP address of the droplet, so I couldn’t really create a new droplet, and quickly switch. I’d have to wait for the new DNS information to propagate.
These issues were in the way of progress, so I decided to take some more time to rearrange things.
Introducing MailComments
Many people use Disqus as a commenting system for their (static) blog. It’s a free service, easy to get started with, and it has everything you’d expect from a commenting system. It’s free up to the point where Disqus decides to show advertisements alongside the comments, and these advertisements are so bad, you will look for better options very quickly. The way out of advertisements, of course, is to start paying for their services. Actually, I would have paid already for their service, if only they would have reduced the tremendous amount of stuff they load on your page. And the cookies they need for tracking you across the internet of course.
Is not writing tests unprofessional?
Triggered by Marco Pivetta who apparently said during his talk at Symfony Live Berlin: “If you still don’t have tests, this is unprofessional”, I thought I’d tweet about that too: “It’s good for someone to point this out from time to time”.
I don’t like it when a blog post is about tweets, just as I don’t like it when a news organization quotes tweets; as if they are some important source of wisdom. But since this kind of tweet tends to invoke many reactions (and often emotionally charged ones too), I thought it would be smart to get the discussion off Twitter and write something more nuanced instead.
Using phploc for a quick code quality estimation - Part 2
In part 1 of this series we discussed the size and complexity metrics calculated by phploc. We continue with a discussion about dependencies and structure.
Structure
This section gives us an idea of how many things there are of a certain type. These can be useful indicators too. For example, if the number of Namespaces is low, there may be a lack of grouping, which is bad for discoverability. It’ll be hard to find out where a certain piece of logic can be found in the code. Too many namespaces, relative to the number of Classes/Interfaces/Traits, is not a good sign either. I would expect every namespace to have a couple of classes that naturally belong together.
Using phploc for a quick code quality estimation - Part 1
When I want to get a very rough idea of the quality of both code and structure of a PHP code base, I like to run phploc on it. This is a tool created by Sebastian Bergmann for (I assume) exactly this purpose. It produces the following kind of output:
Directories 3
Files 10
Size
Lines of Code (LOC) 1882
Comment Lines of Code (CLOC) 255 (13.55%)
Non-Comment Lines of Code (NCLOC) 1627 (86.45%)
Logical Lines of Code (LLOC) 377 (20.03%)
Classes 351 (93.10%)
Average Class Length 35
Minimum Class Length 0
Maximum Class Length 172
Average Method Length 2
Minimum Method Length 1
Maximum Method Length 117
Functions 0 (0.00%)
Average Function Length 0
Not in classes or functions 26 (6.90%)
Cyclomatic Complexity
Average Complexity per LLOC 0.49
Average Complexity per Class 19.60
Minimum Class Complexity 1.00
Maximum Class Complexity 139.00
Average Complexity per Method 2.43
Minimum Method Complexity 1.00
Maximum Method Complexity 96.00
Dependencies
Global Accesses 0
Global Constants 0 (0.00%)
Global Variables 0 (0.00%)
Super-Global Variables 0 (0.00%)
Attribute Accesses 85
Non-Static 85 (100.00%)
Static 0 (0.00%)
Method Calls 280
Non-Static 276 (98.57%)
Static 4 (1.43%)
Structure
Namespaces 3
Interfaces 1
Traits 0
Classes 9
Abstract Classes 0 (0.00%)
Concrete Classes 9 (100.00%)
Methods 130
Scope
Non-Static Methods 130 (100.00%)
Static Methods 0 (0.00%)
Visibility
Public Methods 103 (79.23%)
Non-Public Methods 27 (20.77%)
Functions 0
Named Functions 0 (0.00%)
Anonymous Functions 0 (0.00%)
Constants 0
Global Constants 0 (0.00%)
Class Constants 0 (0.00%)
These numbers are statistics, and as you know, they can be used to tell the biggest lies. Without the context of the actual code, you can interpret them in any way you like. So you need to be careful making conclusions based on them. However, in my experience these numbers are often quite good indicators of the overall code quality as well as the structural quality of a project.
Dividing responsibilities - Part 2
This is another excerpt from my latest book, which is currently part of Manning’s Early Access Program. Take 37% off Object Design Style Guide by entering fccnoback into the discount code box at checkout at manning.com.
Make sure to read part 1 first.
Create read models directly from their data source
Instead of creating a StockReport model from PurchaseOrderForStock objects, we could go directly to the source of the data, that is, the database where the application stores its purchase orders. If this is a relational database, there might be a table called purchase_orders, with columns for purchase_order_id, product_id, ordered_quantity, and was_received. If that’s the case, then StockReportRepository wouldn’t have to load any other object before it could build a StockReport object; it could make a single SQL query and use it to create the StockReport, as shown in Listing 11).
Dividing responsibilities - Part 1
I’m happy to share with you an excerpt of my latest book, which is currently part of Manning’s Early Access Program. Take 37% off Object Design Style Guide by entering fccnoback into the discount code box at checkout at manning.com.
Chapter 7: Dividing responsibilities
We’ve looked at how objects can be used to retrieve information, or perform tasks. The methods for retrieving information are called query methods, the ones that perform tasks are command methods. Service objects may combine both of these responsibilities. For instance, a repository (like the one in Listing 1) could perform the task of saving an entity to the database, and at the same time it would also be capable of retrieving an entity from the database.
You may not need a query bus
“Can you make a query bus with SimpleBus?” The question has been asked many times. I’ve always said no. Basically, because I didn’t build in the option to return anything from a command handler. So a handler could never become a query handler, since a query will of course have to return something.
I’ve always thought that the demand for a query bus is just a sign of the need for symmetry. If you have command and query methods, then why not have command and query buses too? A desire for symmetry isn’t a bad thing per se. Symmetry is attractive because it feels natural, and that feeling can serve as design feedback. For instance, you can use lack of symmetry to find out what aspect of a design is still missing, or to find alternative solutions.
