Quality
His code is like a Rolex.
You look at his gherkin, and smile. It says what it's testing, in plain English, and there's nothing else on the page to confuse or distract you... just English.
"Why then, did our unit tests give me a feeling of dread?" I asked myself. It was quite obvious, that even though we used a neat, little NuGet package, called BDDfy to allow us to write English gherkins, our code was littered with private methods and other necessary evils:
MyTestClass()
{
_subject = new Subject();
}
[Fact]
public void WhenNoOneReadsYourBlog_WriteABunchOfCrap()
{
this
.Given(_ => _.NoOneReadsYourBlog())
.When(_ => _.YouFeelLikeWriting())
.Then(_ => _.JustWriteABunchOfCrap())
.BDDfy()
}
private async Task IAmADumbAnnoyingPrivateMethodThatNoOneWantsToSeeAsync()
{
var IMyInterface mockableMockObj = Substitute.For<IMyInterface>();
mockableMockObj.SomeStupidMethodThatNoOneReadingTheTestCaresAbout
.ShouldReturnSomethingElseInsteadOfNotDoingSomethingElse();
for(var i in someStupidComplicatedIteratableThing)
{
await WhyAmIEvenHereAsync();
}
}
"If we could just hide all the non-gherkin stuff, that would make the code more pleasing to read, understand, and work with," I thought to myself. So I suggested to my team that we use a partial class. We put the public methods, with the English definition of the tests in one file, and everything else in another. The team loved the idea, so that is what we do.
Now, we still have many tests in a file (See how I organize unit tests here). So, the question is, are the tests still useful, to understand what the system does?
Let me put it another way... how do you know enough?
Simplification
The company I work for, IHS Markit, is merging with S&P Global. The combined company will have a hundred gazillion staff members, but only 6 divisions. How do you know what S&P do? You list the 6 divisions.
The universe consists of 200,000,000,000,000,000,000,000 stars. Perhaps it can be summarized as a bag of galaxies.
It takes many years to learn about the human body, but you can summarize it as five things: head, neck, body, a pair of arms and a pair of legs.
Simplifying complexity into a tree, where each node has about 5 children, makes everything easy to understand.
Microservices is the modern, cool way to develop distributed systems. AWS S3 consists of 300 services. I haven't seen this architecture, but I imagine if they're just a list of services that call each other higgledy piggledy, then AWS has a big problem. Our software has 30 services, and even that is a lot to try to understand.
My point is, that I think pretty much everything in software, and perhaps even life, needs to be broken down into a tree, limited to about 5 child nodes per parent to make it easy to understand. Now, don't get me wrong... 5 is more of a thumb suck than anything else, but 5 is a handful.You may be wondering, well, what if it can't be broken down?
- Maybe I have a property for each country... well, that's just a bag, collection, list, or array.
- Maybe my system just has 10 things it needs to do... categorize them... facilities, business logic, etc.
Problems with flat, rather than code organized in hierarchies, adding to complexity are:
- Private methods, private fields and private classes clutter the code, making it more difficult to understand than it needs to be.
- Long methods.
Normally we wouldn't organize classes in a flat structure. We'd use a hierarchy of folders. I think it would be interesting if a class or namespace was a folder. Perhaps an IDE plugin could be written. It might look like this:
Contemplation
Consider code within classes too.Would limiting methods to 5 per class or interface help to make it easier to understand? The interface segregation principle suggests keeping interfaces "small" to prevent having classes that have to implement methods unnecessarily. It may require a little less thought, to have alarm bells going off in your head when you reach 5 methods, to consider whether another interface is required.
Can limiting properties to 5 per class make them easier to work with? I've seen some pretty large view models. Code becomes much cleaner when they're broken down into a tree structure. It can be tricky to change it later, so best to keep them small from the start.
Can limiting lines to 5 per method make the logic easier to follow? Uncle Bob says, "extract, extract, extract." If you follow that, your methods will be pretty small. Using the number 5 might be too artificial, but when you have to scroll to see your whole method, you've probably gone way too far.
I've heard a suggesting that methods should only have 3 parameters. The suggestion is that if there are more, they should be in a class.
Disclaimer: As I've only thought of some of these ideas recently, I haven't experimented with these ideas very much. So, I'm going to try them out, and see how it goes.
Thoughts?
Final Thoughts
Image credits:
https://www.freeimages.com/photo/skeleton-pocket-watch-back-1637098
https://www.freeimages.com/photo/nebula-space-astro-photo-astronomy-sky-1420873
https://www.freeimages.com/photo/burning-tree-1377053
https://www.freeimages.com/photo/dave-in-window-1553933