Below you'll find all issues of my newsletter.
There are only two hard rules when doing code review with your coworkers:
- Keep it professional. Don’t. Get. Personal.
- Don’t take it personal.
Remember that you are talking about letters and symbols in files. Nothing more and nothing less.
You are doing this to improve the results, the software.
You are not your code!
If you want to measure the complexity of your software, there is a lot of software, tools and software-as-a-service offerings available. These options can seem daunting and have a lot of onboarding time (the time it takes you to understand how to use them and get meaningful results).
If none of these things work for you, don’t despair. There is a simple way to get a high-level view on the complexity of your software. And it’s language-agnostic. It doesn’t care whether you write CSS, Ruby, Java or something else.
I wanted to add something to the topic from two days ago: Quality in the eyes of your users.
There is a thing I did not mention. A practice that could help you and your team achieve a higher quality of your products:
- Show your work early and often.
- Improve after receiving feedback.
- Repeat from step 1.
In computing, an interface is a shared boundary across which two or more separate components of a computer system exchange information. (Source: Wikipedia.org)
You develop a web application that has a frontend for the users and a backend for the business logic and the data persistence. (This is a simplification, bear with me for a second.)
Your frontend accesses the data from the backend through an API that the backend provides. This is the first interface. It’s right there in its name Application Programming Interface. But let’s ignore that one for another second.
How does your frontend consume the API? Did you wrap the calls to the API in its own class in the frontend?
I bet that most people reading this won’t have UAT or QA. So what could you do to still achieve quality in the eyes of your users?
Yours users will spend more time with your software, like it and recommend it more, when they are happy using it. If we’re honest it might even be enough to make them not dislike the software. There is so much crap software out there, that people use to get their job done, that the bar is pretty low.
During the last months I wrote a lot about quality and how to develop high-quality software. These letters dealt with topics like linting your code, testing and documenting it.
I also wrote about the different perspectives and motives that might exist in your team.
But there is one view that I omitted more or less: The external view of your customers. They expect to receive and use your software. They expect it to be without bugs and to fulfill the role they “hired it for”.
I am an expert in writing and working with Ruby and Ruby on Rails. But today I was in a fortunate position to realise something: By now, I am language-agnostic. With one of my current clients, I am working with Node.js and Angular. There’s even some PHP in there. My client knew that I haven’t worked with any of these technologies before. Yet they wanted to have me anyway. Even for a price that was above their initial budget.
Today I want to share a small little idea with you. An idea that can have grave consequences if misregarded:
When you schedule a meeting with your team, also share with the team who is responsible for taking minutes/notes. One person has to be responsible for that.
Since I strongly believe that you can only achieve high-quality work if you trust your teammates, I am trying something today. I trust you.
I will show you a skeleton in my closet.
Over the weekend I had (kind of) a conversation with a good friend. The topic revolved around doing the work on software projects, and how that is sometimes harder to do in a right way. Because of external factors, or because of company policy. In essence, this creates frustration. Probably nothing new there for you.
If you want to run a marathon, you have to train for it. Very few people can do that without deliberate training. You have to run for many kilometers consistently and do speed and interval training in between. If you let your training slip, it means your performance on race day will be worse.
I believe in improving the quality of your software projects. If you want to improve something, you have to measure it first. That idea was introduced by Peter Drucker, the famous management book author.
Now if I ask you, what metrics you could measure about your code quality, would you have an answer?
I spent the day at a new client’s office. They hired my to do a complete code quality and security audit for their website and shop system. They are rebuilding and relaunching it. The app is built using Ruby on Rails.
From the feedback I got for my questions and letters regarding the quality of software projects, I can tell you one metric software developers look for.
Commenting code and documenting it has been a topic in these letters already. I linked to resources on how to write docs etc. For the future, this might not be necessary anymore. Because you can have a machine write the comments for you. There is a research project done by Chinese researchers Xing Hu, Ge Li, Xin Xia, David Lo and Zhi Jin named “Deep Code Comment Generation”.
Yesterday I went to an exciting event. The topic was “Can Artificial Intelligence synthesize software?”. The company Seerene organized the event. I haven’t heard about them before, but they are just what I like. They analyze code and projects for optimization potential and defects. I started the conversation with them, let’s see what comes out of it.
When you want to go on vacation, somewhere far away, where you haven’t been… How do you decide for the hotel? What language speaks to you on the hotel‘s website? What images convey to you that this might be a good hotel? Do you only follow suggestions by a friend? Do you care about the vicinity to tourist attractions or important sights? How did they get your attention?
Imagine you are doing a software project. It is mostly going like planned. Things happen. You anticipated them and prepared for them. But there are days when unexpected things happen:
- Stack Overflow is down, and your developers suddenly aren’t as productive as usually 😜
- Slack is down, and communication is halted. Everyone freaks out, and no work gets done.
- Your hoster has problems with their energy and their emergency energy, and servers stop and reboot. You have to take care of this.
- all kinds of things…
To achieve high quality in your team’s code, you should use tools like a static analyzer. These analyzers give you lots of metrics. One is the cyclomatic complexity. A very reduced definition is, that the more complex your methods are, the higher the cyclomatic complexity. A high complexity results from many different paths the program can take while running your code. Many conditionals (
else) or branches in your code lead to higher complexity.
If you paint a fence, you need to make sure to prepare the wood. Take coarse-grained sandpaper and sand the old paint. You have to take it off the wood completely. Once you are done with it, you should use a primer and put it onto the wood. Let it dry for a few hours. After the primer has dried, you take your color and apply it thinly.
Let it dry for another 6 hours. The next step is to apply the color again and let it dry again. Afterward, you can decide whether you need protective paint/lacquer, to guard against weather conditions. That depends on your location.
Do you know the term technical debt? Wikipedia describes it as “a concept in software development that reflects the implied cost of additional rework caused by choosing an easy solution now instead of using a better approach that would take longer.” (https://en.wikipedia.org/wiki/Technical_debt)
This is certainly a correct definition, but there’s more to it. We’ll get to that shortly.
If you read these letters for a few issues, you might have already noticed that I like quality in software engineering. I try to optimize for quality and enhancing the quality of a project leads to more successful projects and more satisfied clients.
If you care for the quality it can lead to situations where you have to stand your ground to achieve the goal of increasing the quality (or your processes or your products). Because doing high-quality work also increases the costs of a project. And it’s rare that managers don’t care for the cost of a project.
The latest Chrome beta (version 70) introduces changes to the Shape Detection API and the Web Authentication API.
The Shape Detection API consists of three APIs: A Face Detection API, a Barcode Detection API and a Text Detection API. Given an image bitmap or a blob, the Face Detection API returns the location of faces and the locations of eyes, noses, and mouths within those faces. To give you rudimentary control of performance, you can limit the number of returned faces and prioritize speed over performance.
They cannot (yet) compare faces and recognize known faces in the browser. Give it a year. Soon browser plugin creators are able to scan the photos you upload to Facebook and identify the people you had fun with last night. If you think I am exaggerating, please wait for the next paragraph.
Imagine you have a team member that always criticises your work. You make commit after commit and put your best effort forth, you try to find the best names for variables and methods. You check your code using tools like RuboCop and Linters. Yet in every pull request, he asks you whether you considered refactoring objects. Things like extracting some logic out of a class, introducing view models and repository objects and sometimes even crazy stuff like domain driven design ideas. Why can’t he leave you alone?
I tell you why: Because the fundamentals matter. They make the difference between software projects where things go smoothly and projects that just fail.
The other week I went on vacation with my family. We flew to Switzerland and had a really great time. I took the big camera to make gorgeous shots of my wife, my baby daughter and the Alps. The iPhone camera is great but pales in comparison to a professional camera. As I am no great photographer you can see this in every shot. But still, the pictures I made with the DSLR are just better. When using a big camera I always try to take more time for the composition of the shot. I use the lens, different focus spots and depth of field way more than when shooting with my phone.
Imagine you are about to go on a trip. Perhaps with your partner or some friends. You want to take the car into the woods, to a place you have never been. The vacation spot has a nice house with a pool and a barbecue. The woman you rent it from stocked the fridge with cold drinks. And they have water beds. And WIFI! IN THE WOODS!
You probably already noticed from the title of this letter, the topic of documentation is still important to me. Now that I began spending time with it I notice the many different aspects of documentation. And there’s more than I thought.
Today I want to share a resource with you that taught me about the four different levels/types of docs. I didn’t even know that there were four levels, or why they mattered. They start with something very important:
It doesn’t matter how good your software is, because if the documentation is not good enough, people will not use it.
I received great replies to my letter last week. I want to quote two for you today.
First is Jacob Wyke on the question why these people become some kinds of star for you an me.
I think its because they teach people things, and so generations of developers look up to them as they taught them things.
Do we have software development stars? I was wondering. We have people like David Heinemeier-Hanson who created Rails. We have Martin Fowler and Uncle Bob, among several others. Are these stars?
I am going to drum the quality drum again. This is a big topic and I know for a fact that I haven’t even scratched the surface of what there is to say about it.
About a month ago I wrote
I’d like to admit, I never had a mentor or teacher who showed me how to properly document software. It was all learning by doing. If you don’t mind, I’ll take some future episodes of this newsletter to document (see what I did there? 👅) my findings and further thoughts about this topic.
This is one of these letters about documentation. My knowledge hasn’t grown by as much as I would have loved, but I read some interesting articles about docs. I want to share these with you.
You might remember that I told you about my “type”, the INTJ (Architect). Reader Gary wrote in to share his thoughts about that (quoted with permission):
So I’ve been busy at my client’s today. I had to implement a sidebar navigation with React. I did something like that a few years ago already and could now redo it for this client. This was great because I could build on my knowledge from the last years. And that’s why I got totally lost in time… I bet you understand. 😉
Last week we talked about quality, and how you could measure it in other’s projects but also your own. Today I want to think about how we can achieve a certain level of quality. But more important: How can we make sure we always achieve this level in our projects.
My brother reads these emails as well, and responded with some interesting thoughts re: quality. Shared with permission:
Aside from hard metrics that are often difficult to install, there’s also a lot of experience involved. I look into details like communication, discipline, timetables and overall presentation of the topic and the approach of the presenter.
Does it “feel” right/good/viable or are they just putting on a good show? One major category is the quality & depth of their questions and documentation. If those offer good quality and are well structured, I usually find the rest of it also well produced.
If you buy a piece of furniture, like a chair, you can compare it with all the other chairs in the exhibition. You can sit on them and compare how they feel. You get a feel for the wood, whether it‘s cheap or high quality.
How do you do that with code? Once the software is released you are able to compare and evaluate. But before?
When developing software you usually optimise for some aspect of the creation process. There are many things when considering a software development project like accessibility, usability, user satisfaction, delivery/deployment speed (release cycle), correctness of the code/app, developer happiness and many more. Some of these are first level concerns, some are on lower levels.
Today I want to share a small utility with you. I am a heavy user of Git, for years now. I am confident to use it on the command line, yet I still come back to using the application Tower (for Mac) regularly. Something about a visual representation other than the Terminal attracts me.
My freelancing since January couldn’t go any better. I am happy, I am learning and I am challenged. But I already know, that freelancing for clients isn’t everything I want to do. This is, and always was, supposed to be the first step into the “right” direction.
I read lots of articles by other freelancers and entrepreneurs who shared the “why” behind what they do. Today I want to do a bit of the same. Perhaps you’ll find it interesting as well?
Did you hear about the European Union polling its citizen about whether DST is really necessary?
Because I thought it’s funny I sent this issue an hour later than usual.
I was wondering what happens with our apps and services, if DST suddenly isn’t “necessary” anymore. The offsets for saved timestamps become invalid?
Yesterday I got my hair cut. The hairdresser was rather chatty and told me all sorts of things. When her friend came in they went on to lamenting about how bad it is for them. Both dislike their jobs, the payment is bad and they‘d rather do something else. But they don‘t know what…
“The Inner Platform Effect is an anti-pattern that occurs when a software system is designed to be so customizable that it ends up being a poor imitation of the platform it was designed with.”
Matthew has started a new series on anti-patterns in software development.
As I previously mentioned I freelance for a nice client right now. I am embedded into a great team and like working with these people. Summer came and our project manager was about to take his vacation. (He cycled from Finnland to Hamburg in Germany with a friend, in case you were asking. I think that’s great as I am a cycling maniac myself…)
Before he started his vacation we groomed the backlog in Trello and scheduled various tasks for me and the other freelancers. I had the seniority in the project during his absence, so I took on the load to manage the others.
After scheduling a few tasks we looked at each other and decided to schedules some more, because it felt like these were too few during his three week leave. Then we scheduled some more “just in case” we were super fast.
When was the last time you needed to display a formatted date somewhere in your applications? Since I work a lot on React (or generally JS) apps these days, I recently had the “pleasure” to format dates in JS. After receiving them from a Ruby API. Which in turn takes the (Postgres) db timestamps and converts them into Ruby (date)time objects. Oh the fun we had. “Of course” standardizations saves your ass in this situation. Usually at least.
This is another email I am sending while being happily busy with our newborn.
Two days ago I linked you to an article about Livable Code. Today it’s about reading code. While learning software development I often heard the phrase that you should read other people’s code because it makes you better.
I have to admin, I never purposely did so. Well, one time, I followed through the Rails framework to understand how an HTTP request is handled. But that was the exception. It turns out, I am not alone:
This is another email I am sending while being happily busy with our newborn.
My first job was as a software developer at Ericsson in Montreal, working with the mobile switching center that handles calls in a cellular network. There was a lot of code controlling call set-up, hand-offs, roaming etc, but I was pretty disappointed to see that it was all done with quite basic data structures and algorithms. The most interesting part I found was the code keeping track of roaming subscribers currently in the system. It consisted of one thousand binary trees, where the last three digits of the subscriber number determined which tree a given subscriber belonged to. To find a subscriber, you picked the tree based on the last three digits of the number, then traversed the tree to find the subscriber. Apart from that, it was pretty much only linked lists or simpler.
This is another email I am sending while being happily busy with our newborn.
Sometimes things don’t always go as planned. Code breaks, servers crash, or a product doesn’t work – you know the story.
First of all, sorry for not writing to you yesterday. I spent the day in the hospital with my wife. Our second daughter was born on 1:20pm yesterday and we couldn’t be happier. Mother and daughter are both very well. This is the reason why I won’t be able to continue writing my usual emails for the next few days. But I will continue sending you emails. The content will be mostly “written” by other people though. 😉
Today I want to share a recent article by Uncle Bob: Too Clean?
A week ago I mentioned my Automation project: Factory 0.1. During the last week I managed to get it to a point where it works. Today I wanted to tell you a bit about it. This will be a lengthy, nerdy post about details and automation.
Since I love reading I thought I switch things up for today and share a small list of books I enjoyed (and why I enjoyed them).
All links are no affiliate links.
You walk into a room. You haven’t been here before but you need to find something. Your friend told you, that you’ll find it there: “It has to be there somewhere. Please just take a thorough look around!”. You find old snack boxes , papers upon papers and stuff that you wouldn’t want to touch because it looks like it might already be alive. A distinctive smell permeates the room. You don’t want to be in here for too long. But you want to find the thing…! After looking around for 10-15 minutes you notice that you lost track of where you’ve already searched before. The whole mess is just too much for you.
Yesterday I told you about our struggles with the new door bell. While, sadly, this state is still unchanged, there’s another story there that relates to software development: The new door bell needed some power. The old one did not need this much power (230 volts), so there were no appropriate power cables laying around. That’s why we cut a different cable that lay in the vicinity but usually powers the automatic gate for the car. The plan was to have something like a t-shaped connection between the cables. So the gate would still have power, but a new cable would lead to the door bell and everything would be fine™. So I cut the power cable to the gate. What I did not know at the time was, that there are literally t-shaped connectors for power cables (not an affiliate link, just for reference. Don’t buy it! 😉).
Over the course of the weekend we tried to install a new door bell for our house. The old system is really old, falls apart and works only some days. So we bought something from a respectable German engineering company named Gira. They make high quality products and we had prior experiences with their parts. We also happen to really like their clean design language. The reviews online spoke about easiness of installation, “connect just a few wires”, nothing can go wrong there.
Where I sit writing this email, today is Friday. So tomorrow the weekend starts. Do you already have plans for the weekend? Perhaps we’ll go to the lake, because it’s scorching hot in Europe these days. But I will also continue with my “Automation project: Factory 0.1”.
My home computer in 1998 had a 56K modem connected to our telephone line; we were allowed a maximum of thirty minutes of computer usage a day, because my parents — quite reasonably — did not want to have their telephone shut off for an evening at a time. I remember webpages loading slowly: ten to twenty seconds for a basic news article.
“When did you reach the point where you didn’t need to read another research report, didn’t need to absorb another scouting analysis, didn’t need to stop by the bookstore… because it simply wasn’t useful or efficient to learn another thing about your field?”
This question was posed by Seth Godin. Seth is big in marketing and entrepreneurship. Perhaps you already know him.
This question is a deep one.
This morning I was visiting the hospital with my pregnant wife. She’s in the 39th week and over the course of the weekend we had some concerns regarding the health of the baby. So we went to the hospital to have everything checked. They made a CTG for the heart and vital signs of the baby.
In this enlightening article from the New York Times, Charlotte Graham-McLay reports about a company from New Zealand that tried something out. They switched all their employees to work only 32 hours per week instead of the regular 40 hours. All of them still received the same salary for 40 hours though. What they found was that their productivity increased and the employees got the same amount or work done. Sometimes even more. To reach this level of productivity, they reduced meeting times, didn’t leave early or took longer breaks.
Please excuse this email’s subject line. Did you receive an email like that before? As I wrote a few days ago, I did.
I am currently reading a very interesting book: “Principles” by Ray Dalio It was recommended to me by several sources, most notably by Sebastian Marshall. Sebastian focuses a lot on personal improvement in his work. I value his ideas and ideas very much. So it made sense to me to follow his recommendation to read this book.
Test-driven-development. There’s no other way to do this.
A few days ago, a friend told me about the construction site that is located right outside the window of his living room. He was, understandably, complaining about the construction workers starting their shifts at seven in the morning. They make all kinds of noises and it’s costing him his nerves.
perhaps you remember one of my last newsletters, back when I wrote them from the 5minutenpause.com domain. I told you that I switched the content format to plain text and that I do not track click and open rates anymore. Well I do again.
A few days ago I received an email from my bank where I keep my business account (n26 if you want to know), informing me that my personal details including email address, first and last name and telephone number were stolen during a hack that occured at Typeform.