CONFIDENCE, OR: HOW TO ASSESS YOUR COWORKERS

Today I’d like to answer a question.

As a (project or product) manager, how am I able to assess whether my coworkers write good code?

It’s is a good question. It’s easy to see why a development team lead might want to know whether her direct reports write good code. And she probably has pretty easy means to find out. A project or product manager might care just as much—or he might only be curious. Either way, how could he judge the code quality?

Related to Friday’s email, if you wanted to know something about the software quality, you could ask your clients or users. Or you might already know because people are usually quick to share their opinions especially if something is wrong.

The quality of the code your coworkers write can be assessed with quality metrics.

You can take relatively simple metrics like

• lines of code (per class, per file)
• number of commits per author per day

Or you could use a software as a service offering like CodeScene or CodeClimate or SonarQube. These offer advanced metrics that take a little more “Code-Fu” to gather.

The most straightforward, most effective metric is another one: Ask them! They are developers and work with the code all day. They will have an opinion on it. Perhaps they have a hard time to explain something they don’t like, depending on their seniority. But you will get some measure of quality. The more people you talk with, the more opinions you can get. And if their views are orthogonal to each other, you can offer to use static analysis to settle the debate.

The question I received had a second part as well:

… and how can I get them to improve their code?

I will offer an opinion on that one tomorrow.

DELETE ALL YOUR TESTS!

Sorry for not writing yesterday. My schedule did not allow it. I refrained from posting anything since it wouldn’t have been of sufficient quality for you.

On Monday I tried something new. I recorded the content of the newsletter as a video and posted it to YouTube and LinkedIn. While it didn’t exactly blow up, I am happy and excited about these changes. I want to try to stick with this. Today I switched things up. I first recorded the video, of which I’ve embedded a link to below, and then wrote the newsletter.

https://youtu.be/7FRYUE_waWk

The subject says it already: Delete all your tests!

Don’t worry, I still believe in test-driven design (or development, but for me, it’s more design… perhaps a topic for a future video/email?).

There is a point in every application’s lifecycle where you reached a stable point for a majority of features. You used tests to keep your quality high. You passed acceptance tests from your clients and their users. The thing runs. Now your test suite is hundreds or thousands of tests long. It runs for minutes or even hours. For every commit, the whole suite is run. Future development could be faster, but CI takes ages.

Here’s what you should do:

• Find the stable parts of the application and extract them. Turn them into a library. Librify them, as I say in the video. This isn’t a word. I looked it up. The suggestion is to call it packaging or archiving. But I like librifying better. Please excuse me, but I will continue calling it that way. You’ve been warned. 🚨
• Delete all tests that concern your library from your application.
• Go on developing things.

If you reach a point, where you need to extend the library, just recover your tests concerning that specific part from your version control system.

Why should you do this?

Every application is a legacy application.

The less code and tests you have to care for or keep in mind how they work, the less stressed you are. It reduces your mental load and frees your mind.

Your application does not need to have corners of code, that no one touches because no one knows how they work anymore. Extract them and choose a proper name for your library. It will keep your code lean, and your future tests will run quickly.

TESTING STRATEGIES - TEST MANAGEMENT

You don’t need test management. You develop web applications. Your job is not rocket science. It’s demanding, and you are doing a fantastic part shipping features and making customers happy. Who needs test management to do that, right?

Let’s try three different points of view on this:

The software developer’s Pov

You code and you write tests, even perhaps before writing application code? Different project managers come to you with their projects and ask you to be part of the team. You have a reputation with them that you are able to ship. You have your hands in several projects and can choose which ones you would like to work on. Your manager sets up an appointment for the yearly review. You want to ask for a raise. On what ground should you get your raise? Because other employees value you and your work? Because of your reputation?

What about this? You can click a button and produce a long report sheet that lists your contributions to several high-value projects. The report links your contributions with the JIRA ticket number, the commits that went into the feature and a detailed report of the tests associated with the feature/ticket. Your manager can also easily see, that tests for your code are successful in > 90 % of all cases, throughout the whole year. Compared to other developers you spent 19% less time per ticket and your bug tracker shows that code you wrote has the lowest propensity for defects.

The project manager’s Pov

You handle two to three projects in parallel, know the backlog to these projects by heart even though each one is pretty long and try to manage your clients on which features will be released when. You are aware of contractual requirements and the need to comply with certain regulations. Your clients could ask you to produce a report on the software’s quality and you would send it back within the hour. The client could see the user stories she created together with your team and she would also see that all of these were tested throughout the whole development cycle. She is satisfied and feels safe with your company since this report also made clear that you are doing regression tests for the integration with the legacy book-keeping system from IBM that sits in the client’s basement.

The manager’s Pov

Starting the project was a risky business decision. You are dealing with a heavily regulated environment. Any mistake could cost your reputation, but also your job and lots of money. You ensured the government official that your company would be up for the job because you have automated processes that document changes and outcomes. Risks are monitored and documented as well. The continuously running test suite is tied back into everything your employees create or modify, which gives you peace of mind because you don’t fear the audit.

What’s test management

A proper test management software will hold the project’s requirements in an easily searchable way. You specify and create test plans that are linked to requirements. This link offers traceability. All types of tests are supported (Black-Box, White-Box, change-related tests, functional and non-functional tests). There are JIRA plugins that’ll offer that, but there is off-the-shelf software as well.

If you integrate this software in your workflows, you should make sure to write the proper tests, which will be how we continue next time.

TESTING STRATEGIES - BACK TO START

On Friday I gave you a very quick intro on how you could increase your test coverage and confidence for an application that has no tests. You can consider this the quick and dirty approach that works, when you have little time and just want to start somewhere.

Perhaps you should start at an earlier point. A proper way to start the journey to testing software is the state the question

Why do we test software?

The answer to this question is rather long. For any given project, the objectives of testing may include:

• To prevent bugs
• To find failures and bugs
• To evaluate requirements, user stories, design, and code
• To verify whether all specified requirements have been fulfilled
• To validate whether the software is complete and works as the users and other stakeholders expect
• Document and compare quality of the product
• Provide sufficient information to stakeholders about the level of quality the software achieved
• Reduce the risk that undetected failures occur in production
• To comply and verify compliance with contractual, legal, or regulatory requirements or standards

There are many ways that a software project can have defects. Exhaustive testing can help in reducing the risk that any of the many possible defects leads to a failure in production. Without tests you can only hope that nothing serious happens. Experience in writing software is not enough to guard you against introducing errors into your software. You wouldn’t need to write automated tests for all these bullet points above. Testing can be done manually, through peer-review or other means as well.

To make sure that you covered the important parts and reduced the risk for defects effectively you need test management. Test management isn’t everything in your /tests directory. Linking issues in your project management tool to a risk assessment list, verifying that important documents and decisions were reviewed (or tested) and documenting all the work that goes into reducing the number of defects; This can be called test management. But there is more to it. We will get to this later.

TESTING STRATEGIES

In an earlier email I asked you on your opinions as to what you would like to read more about. A bit like a “chose-your-own-adventure” style newsletter. BTW: Did you see that show on Netflix, where you can decide how the story unfolds? This was excellent. Although the nerd in me sees many ways how it was confusing for the user and how it could have been even better. But for a TV show? Wow, I am excited that dared to do that!

Anyway, the majority of the answers indicated that you would like to read something about testing strategies.

In a call I had yesterday, I used the phrase “In a small company, every app becomes a legacy app”. Small companies often don’t have the time or money to test their apps properly. Sometimes the knowledge on how to design and code an application isn’t evenly distributed in the team. Peer review might not prevent mistakes or bad decisions (again: time and money). The state of an application gets worse, the longer it is maintained. When I come to a company with little or no tests and they ask what they should do, I often recommend to create a small risk assessment for the features of their app. Once you know the critical paths through an app and the risks for each you can start to test these features outside-in. Critical paths with high risk differ from case to case, but things like “password forgotten” and “shopping cart payment” are candidates that rank high all the time.

Ideally you would have unit tests for your classes. And integration tests for multiple components. In reality you have nothing. So don’t try to test from the inside, but start at the edges of the application for your critical paths with high risk. Write acceptance tests for these parts. Keep it to one or two tests of the “happy path” where everything works. Once these are covered you can decide whether to start a refactoring or add more tests. More tests could mean “sad paths” as well, or unit tests for some of the more modular components.

This will help you gain certainty that you don’t break your most important features when you start the bigger refactoring. These are also tests that management should have no problem green-lighting because they prevent errors for the parts where money is earned.

ONLY TWO RULES

There are only two hard rules when doing code review with your coworkers:

1. Keep it professional. Don’t. Get. Personal.
2. 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!

INDENTATION AS A COMPLEXITY METRIC

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.

You see, when developers structure their code, they use indentation as a seperation. Some languages/developers use tabs and other spaces. I personally like to use 2 spaces for one indentation step. Others use 4 spaces (that’s common in JavaScript as far as I know). In the end it doesn’t matter, because every indentation increases the complexity by one.

Like this:

def my_function () {
  if (this_is_true) {
    do_a_thing()
  else if (another_thing_is_true) {
    if (one_more_check?) {
      // we are really far into the rabbit hole right now
      do_a_different_thing()
    }
  }
}

If you count the indentation for this pseudo-example-code (a heavy mix of Ruby and JavaScript, just to make you not try to read the code but understand the concept), you see that the biggest indentation is already at three. I adhere to the rule to never indent SCSS files more than three times. And that might already be too much. SCSS-lint counts these indentations and reports them as errors. You could use the same metric for any other language.

If you or your developers indent code more than 2 levels, there might be a problem lurking that you should investigate.

This check can probably by done by non-developers as well. You just have to trust your eyes and be able to count to 3. Or 4? 8? You can google “Pyramid of doom” and will get a nice view how this can look in its worst case.

Have fun counting indentation!

Yours, Holger

SHOW YOUR WORK

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:

1. Show your work early and often.
2. Improve after receiving feedback.
3. Repeat from step 1.

Results get better with feedback. It forces you to consider other points of view from your own. In case the input isn’t valid, you will still explain your point of view to the others. Which in turn helps you understand your personal opinion in a more profound, better way. Your team will establish a feedback culture in which it is normal to seek, accept and build on other peoples opinions. There is no reason to avoid that situation. Receiving and giving regular feedback and exchanging opinions builds courage. In your peers, in yourself. It also deepens the team spirit, because your solutions will come from the whole team. Everyone takes part in finding the optimum and recognizes parts of themselves in different aspects/features of the software. The result is shared ownership. And shared knowledge. Which is always good because you depend less on a singular individuum.

Doing feedback rounds early, also makes it easier to change course, should you find it necessary to do so.

And, there is often this dreaded line:

They client asks when they can see something. What can I tell them?

Having feedback rounds enforces a development culture where people create runnable/viewable results. How often do you have it, that a developer sits at their desk for two weeks or more? When the time comes to show what they have created, the following things might be true:

• they are not done yet
• it doesn’t look like the spec
• it does not work reliably or at all
• it does not integrate well with the rest of the product

Early feedback rounds prevent this from happening. When was the last time you showed your work and asked for feedback?

Yours, Holger

INTERFACES

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?

Or do you send GET/POST requests to the URLs of the API directly? How does your frontend expect the data to arrive? Will it take simple JSON, or do you need instantiated classes or objects at your class boundaries? Now imagine you want to exchange the source of your data. You don’t need the API anymore, because you will provide a local database that already holds all the data. Or you provide the json in text files.

How hard will it be for you to change the source of the data? To make the frontend consume the new source, be it text files or a local database (e.g., IndexedDB)? Does your design allow for an exchange like this?

If you answer no to this question, then you have a problem. You did not specify an explicit contract between your data source and your consumers.

It would be best if you encapsulated the responsibility to fetch data from somewhere into one module/class/object (call it whatever you like) and reuse that. It could even be a family of objects if you consume many different endpoints. And these objects need explicit contracts. Calling ProjectsRepository.latest(10) should return 10 Project objects. You should not know where they came from. Now your ProjectRepository might internally call ProjectsEndpoint.latest(10) or something else. It might do something like File.read("./projects.json").take(10) (This is supposed to be pseudocode 😉). You shouldn’t need to care. But you should be able to change it easily.

Yours, Holger

QUALITY IN THE EYES OF YOUR USERS

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.

So let’s imagine for a moment, that you want to exceed that goal and make your users happy. What are ways to achieve that if you cannot do User Acceptance Testing?

Here are a few thoughts:

• Let your developers speak to users when planning and architecting the software. Your developers should try to empathise with your users and understand their problems when using the software. Or better: They should understand the pain that the users try to solve when using your software. After all, they don’t buy it because it’s pretty but because they want to use it to get things done. If your developers understand that pain and can see it through the eyes of the user, they are much more able to create a viable solution to that problem.
• Make your team use the software themselves during a longer period. That way they can experience the problems themselves and will be much more motivated to improve the solution. Of course, this might not be possible for products that are totally unrelated to your field. How should your team use a hospital facility management software, right?
• Let your developers work in support for one day/week. This might not solve fundamental problems your solution could have. But it could bring developers closer to your users—that are already using the software—and help them find ways to improve the situation.

I am curious if you have other ideas that I might have overlooked.

One thing I am sure of: You have to speak with users or become users or get in contact with users. You won’t improve the situation without changing perspective.

Yours, Holger

TWO VIEWS ON QUALITY

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”.

It is not easy to integrate this view into your software development and quality process. Two possible options come to mind:

• User Acceptance Tests (UAT)
• Quality assurance in-house

UAT is the next best thing from deploying/selling your software and receiving feedback. UAT means having real users test your software from end-to-end and gathering their feedback. UAT can help you gain trust from your users. The people taking part in a UAT could be a well-defined group of users from a big company that is one of your clients. If these people test your software and find it performing well, you can gain good advocates for your product. UAT could also be a legal or contractual requirement for your software.

Quality assurance done by a team in-house usually helps companies find problems early and thoroughly. There are ISO certifications for that (ISO 9000). Most companies won’t be able to afford that though. QA is a topic worth a separate email.

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?

We’ll talk about that in the next email.

Yours, Holger

FUNDAMENTALS

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.

I am proud of that.

They wanted me because the language I work with, is almost irrelevant by now. The fundamentals are the same everywhere. When I see an Angular service class (I don’t even know for sure if that’s the right term for that…) that’s 300 lines of code long—I know there is something wrong and that is has too much responsibility. When a constructor for another class calls a different class to set itself up, without that class being injected, then something is wrong!

When a pull request is merged, without answering the questions in its description, and without having a real review, then something is wrong!

I can help my clients in so many ways right now, that I am just really proud and happy about that. Forgive me for boasting about that so much.

So let’s turn to you. I couldn’t have told you all the things I am capable of, three weeks ago. I jumped into cold water and just looked how I could contribute to my client’s success. Turns out, there are lots of ways. Don’t you think you could do the same?

If you work in this industry for a while, you can share amazing amounts of expertise and experience with your peers. If you just entered the field and are still learning the fundamentals, you probably already have experience in a (totally unrelated?) field of work. Let us know about that, and how we could translate concepts from there into our field. Even if that’s not obvious right away.

People are amazing. And if you and your team are able to step away from the stressful work that you have to deal with every day, just for a few moments or hours—I bet you have a lot to share with each other. It happened (again) today for me. And tomorrow it might happen for you.

Yours, Holger

TAKING NOTE

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.

And they should share it with the team afterwards and ideally post it to the Wiki or wherever you store your team’s knowledge. Make clear well before the meeting starts, who is responsible.

If you fail to do that, nobody will be responsible. People will leave after the meeting concludes and noone will remember everything that has been said. If you’re lucky a few will remember the key points. Good luck having successful projects that way.

Schedule meeting, appoint someone to take notes and make these available for every team member (and potential clients). Everything else is doomed to fail.

Yours, Holger

EVOLVE

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.

A few years ago, I worked on an Open Source Content Management System in Ruby on Rails (a OSCMSiRoR 😂). This system is still used in production to this day. The team and I developed it for clients and kept reusing it. Back then I and the others didn’t know a perfect way to develop a CMS. We had been users of other Ruby CMSs but found them inadequate for our use-case. And that’s when you decide to roll your own. 😶

It was designed as a Rails Engine, so it could easily be included into other Rails Apps (Active Admin and Devise work like that as well). I didn’t know as much about software design and architecture back then, as I do now. Every time I look at the source code, I want to rip it apart and redo it. Apply my knowledge and make things better. Looking from the outside in, it seems easy to have small wins that improve the project. The reality is that the apps that use the CMS in production are too heavily bound to it. You cannot just change code in the engine because you would run into trouble in your client apps. I’ve tried.

This is a lesson in itself: You have to decouple your apps from the engines that they use.

What was the single biggest error we made back then when we designed it? We wanted it to work well with all kind of apps. It was supposed to be flexible to be used with Rails apps. But we did not foresee that we would want to redesign the underlying engine at any point in time.

Side-note regarding quality: Above all else, we had too few tests. Changing things without proper test coverage is bound to go wrong.

What would I recommend doing differently nowadays? The idea to have an underlying CMS that works with any kind of app and provides management capability for any kind of content you could throw at it is still a good idea. First of all I would provide an API with a strong contract. Then you could test against the API and it could evolve and things still would work. As long as you fulfill the contract. The content is only provided via this API. The users of your engine won’t ever have a way to access content directly. Second, I would use a document-based database. It lends itself beautifully for this task and you don’t need a relational database for that. Save your content as JSON. Save your attachments/media-objects in there as well.

This email is getting long so I will make a cut here. My laundry list for things to improve or do differently is longer than what I hinted at above. I am dreaming of creating this CMS at some point. Because I can and because I’d like to make it better than last time. You probably know that feeling. If I ever get around to doing it? I don’t know. 🤔

Anyway, I promised to show you my skeleton, so here it is: [https://github.com/5minpause/Goldencobra]

Dare to show me your skeletons?

Yours, Holger

FRUSTRATION

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.

It may be that I describe things in a too positive way for you, here. Perhaps you read my letters and think to yourself, that things don’t work like that in the real world. Maybe you don’t have enough freedom in your projects to be able to care for quality in a way that would satisfy you? If that’s the case, I would like to learn about that. Tell me about your frustrations and the things that hinder you from doing your work. Don’t be afraid to share. I’ll keep everything confidential.

Still, I will continue with my mission to increase software quality and to tell about that world in which software projects are finished on time and budget, with high-quality code and best practices. I do know from experience that this world exists. And even if we cannot get there every day, do not lose track of the goal. If there are even single days, where you can come close to that, these are good days. And striving for raising software quality in your projects will make them better eventually. Constant dripping wears away the stone…

Yours, Holger

HOW TO TRAIN FOR A MARATHON

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.

If you want to deliver high-quality software on release day, you need to measure and work on the quality of your software every day. If you let it slip and don’t take care of issues, they will pile up, Technical Debt will increase, and your quality will suffer.

So, how’s your training going?

Yours, Holger

MEASURE IT

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?

You could measure the average complexity of your classes. Or the churn of your classes (how often they or their content changes). This tells you about spots in your project that you have to keep a close eye on.

There are tools that help you with that. Make sure to measure consistently to get a picture of how things change.

Do you know what the average, or worst, complexity on your last project was? Do you know your current value? Can you compare those and interpret the impact these numbers have on the outcome of your projects? This could be development taking longer, or higher count of bugs.

But you have to measure to know.

If you need assistance in setting these things up, let me know.

Yours, Holger

CODE QUALITY & SECURITY AUDIT

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.

The client asked for my expert opinion about the general code quality as well as specific hotspots like PayPal integration. I will create multiple pages of in-depth analysis and recommendations on how to improve the project.

Starting this project today consumed all of my attention, thus you get this letter now. It’s evening here for me in Berlin and I couldn’t be happier with how the day went. There were points in my past where co-workers snared at my thoroughness and me being (over)precise. It turns out these are very good attributes to have when it comes to an audit like this.

Yours, Holger

ONE METRIC

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.

Test Coverage

Well, that was no real surprise, was it?

Let me tell you another metric:

Documentation

Can you guess who cares for that? Users of your software. They don’t care for tests. But they want to know how to use the thing they paid for. (Even if it’s OSS they do pay for it: With their attention and time.)

Project managers on the other hand might care about both metrics. Most of the time, I’d wager, they care even more about planning and risk management of the project. As I am married to a wonderful wife who works as a great project manager, I’ll verify this statement tonight 😆. (I’ll report back)

The person authorizing the budget might care the most about the costs. And yes, the price (in 💵💶💷💴) people have to pay for your results is a quality metric of itself.

My point is this: While there are many different aspects for the quality of a project, which one you should put a priority on depends on your target audience.

Yours, Holger

LET THE COMPUTER HELP YOU WITH THAT COMMENT

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”.

This is their introduction:

In software development and maintenance, developers spend around 59% of their time on program comprehension activities. Previous studies have shown that good comments are important to program comprehension, since developers can understand the meaning of a piece of code by using the natural language description of the comments. Unfortunately, due to tight project schedule and other reasons, code comments are often mismatched, missing or outdated in many projects. Automatic generation of code comments can not only save developers’ time in writing comments, but also help in source code understanding.

You might be wondering what results they achieved:

Here’s a method they used it for (the method is abbreviated and not shown in full in their abstract) public static void sort(Comparable[] a){ int n=a.length; for (int i=1; i < n; i++){ Comparable v=a[i]; int lo=0, hi=i; while (lo < hi) { … } … } assert isSorted(a); }

This method sorts. I deducted that from its name. Now, here is the comment written by a human:

Rearranges the array in ascending order, using the natural order.

And this is what the computer generated:

Sorts the array in ascending order, using the natural order

:spooky:

Another method:

public boolean contains(int key){
	return rank(key) != -1;
}

The human version:

Is the key in this set of integers?

The machine-version:

Checks whether the given object is contained within the given set.

I like the machine-generated more!

If you ever wrote these comments yourself, you know how quickly they are outdated. Having a machine update these on regular intervals make much sense to me!

Here’s the link to the paper: Deep Code Comment Generation

Yours, Holger

TIME WELL SPENT

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.

Perhaps you have heard of the machine-learning software that can make your holiday pictures look like a Picasso? That’s called Becasso, and that’s done by the people I visited yesterday. It’s a cool achievement to transform a picture into something that looks like a Picasso painting (or just a cool painting…).

Text is more straightforward for machines to understand than pictures. They can recognize patterns more easily. At least that’s my understanding. And everyone here listens to me, right now. So just let us pretend I am right for a second. Cool. Two programmers write code in two different styles. If you and I write the same Ruby program, it will look different. But—if the problem domain is well defined and smallish—it won’t look completely different (most of the times). It should be possible then, to have a machine-learning program that can take my code and make it look like your code. Transform my style into yours. Or vice versa. Or take a style guide, we both decided on, and transform our code into code that conforms to the style guide. Automatically.

I haven’t said this would be useful! Of course, there are problems. There always are. What happens, when somebody has to modify that code. Write a new feature… Will the algorithm change the style again? Can the third developer even understand the code the machine wrote?

And what about belletristic? Could I have a program that turns my letters to you into something like it was written by Hemingway? (See what I did there? I subconsciously made you associate my letters with belletristic, ha!)

Software Engineering will be transformed in a lot of fundamental ways in the next 20-30 years. See you around. 😉

Yours, Holger

DON'T BUILD A FIVE-STAR HOTEL

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?

If you only book 5-star hotels, what qualities do they provide, that others don’t? In case you stay the night at a bed-and-breakfast, what made you choose it?

Think about that for a minute.

Now let’s turn to your projects. What could you do, to get people notice and choose you from a pool of similar projects? What characteristics do you care about? And would it make sense to optimize for those, to attract people similar to you? If you do the project for someone else, do they share your views? Would they rather you optimized for something else entirely? Perhaps that would make their project an even bigger success on their eyes?

I am curious what your thoughts are right now.

Yours, Holger

RISK LIST

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…

What would happen, if you made a list of these things that occur and wrote down how long these took / their impact on your projects? You could also write down what expected risks you already had planned for and their possible impact. Start to make these visible, too.

I bet your list would grow rather long. I also bet it would give you some nice things to talk about with your stakeholders when you plan the next project or feature.

Yours, Holger

CYCLOMATIC COMPLEXITY

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 (if/else) or branches in your code lead to higher complexity.

But why does the complexity matter? I want to give one quite simple reason, that entices a developer to reduce the complexity. It is not because the program is harder to reason about (that’s also true!). Every possible path through your code increases the number of test cases the programmer has to write. It makes sense: If there are three possible paths, the program can take to reach the end of the method, you have to write at least three test cases to be sure everything works. Factor in that you probably will have different inputs to your methods, and the number of test cases increases quickly—because you have to test every path for every possible input. And it gets worse if your method depends on changing states or mutable data…

If you want to make your life easier when writing your tests, then decrease the complexity of your methods. Easy as that 😜

Yours, Holger

HOW TO PAINT A FENCE

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.

If you are in a hurry, you can skip any of the steps and just paint the fence. Of course, that paint will only last you for a few months or perhaps years—if you are lucky and live in an area with “benevolent” weather. But most of the time, you will have to redo you fence soonish and incur at least the same costs for the paint and the time it takes you.

If it’s worth doing your project, it’s worth doing it right.

In case you paint fences, please don’t ask me 😅. But if your software project could need some help, let me know.

Yours, Holger

PS: Today marks the two-month anniversary of me writing daily. 🎉 Thanks for inviting me into your inbox. It’s a pleasure.

PLANNING FOR TECHNICAL DEBT

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.

Yesterday I wrote

Anyway, it’s important to take care of quality right from the start of the project. Don’t fall for the idea of redoing it later. Refactorings are common, useful and will happen, but don’t plan for them from the beginning.

My good friend Tino brought to my attention, that I did not mention an important fact: (paraphrased by me)

Good planing also accounts for planned technical debt, instead of accumulating technical debt during the project because of factors like the cost of the project, fear of delays and bad decisions.

Thanks, Tino!

So why should you plan for technical debt (TD from here on)? A low TD approach is commonly perceived as superior. But, accumulating TD might be beneficial under certain circumstances. This could be that you plan for a very short release to attract early adopters or because you want to be first-to-market in a heavily contended market, or with a new feature. Another point why TD might make sense in your project is the following: TD always has a certain risk associated with it. The risk could be increased costs in maintenance of this part of the application. Now imagine that you create a part of your app, where customers can get in contact with you and receive first-aid in using the software—like a help-desk. You know that, at some point in the future, you will outsource this whole part of the app to a third party who will take complete, good care of your users. Now you can transfer the whole risk of this part and the TD associated with it, to an outside player. They are experts in this thing and won’t use your help-desk module but their own software. So you don’t have to worry about it while creating it, and you don’t have to worry about maintaining it in the future.

This, again, makes it clear why a good plan is crucial for the success of your project and for the quality of your work.

Yours, Holger

STANDING IN FOR QUALITY

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.

A good thing to have in those discussions are case studies about successful IT projects—and what made them successful. An external partner that explains the business case why quality matters would be helpful, as well.

Anyway, it’s important to take care of quality right from the start of the project. Don’t fall for the idea of redoing it later. Refactorings are common, useful and will happen, but don’t plan for them from the beginning. If your design and architecture plans for the project were faulty or of low quality from the start, there is not much you can do later on. Be realistic about the time it will take to create a well thought-through design for your application. Factor in that you might have to create a small poc (proof of concept) to test and compare different approaches if you lack the experience.

Don’t let someone else rush you to do these things. Explain to them that you save time in the long run. What’s the saying?

Weeks of programming can save hours of planning

Yours, Holger

ALL YOUR DATA ARE BELONG TO US

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.

The Credential Management API, enabled in Chrome 51, defined a framework for handling credentials that included semantics for creating, getting, and storing them The Web Authentication API […] allows web applications to create and use strong, cryptographically attested, and application-scoped credentials to strongly authenticate users. Also enabled by default are macOS’s TouchID and Android’s fingerprint sensor via Web Authentication. These allow developers to access biometric authenticators through the Credential Management API’s PublicKeyCredential type.

(Emphasis added by me)

The Web Authentication API draft from 12 September 2018 has a section on Privacy Considerations.

Biometric authenticators perform the biometric recognition internally in the authenticator - though for platform authenticators the biometric data might also be visible to the client, depending on the implementation. Biometric data is not revealed to the WebAuthn Relying Party; it is used only locally to perform user verification authorizing the creation and registration of, or authentication using, a public key credential. A malicious Relying Party therefore cannot discover the user’s personal identity via biometric data, and a security breach at a Relying Party cannot expose biometric data for an attacker to use for forging logins at other Relying Parties.

(Emphasis added by me)

… “depending on the implementation”… I use my fingerprints to access my laptop and used to use it for my phone. I trust Apple. This is my decision. I wouldn’t trust Chrome and web developers to keep my biometric data safe.

There is no point here. Today I have nothing clever to say. Only, I slightly worry what oversight there will be for this data. I know the draft says different, and it seems unlikely, but: When will we see the first headline in the news that a database for the website of StartupCo was breached and, among stolen the data, were some biometric datasets.

History shows that the more ways there are for things to go wrong, the surer it is that they go that way.

Keep safe.

You, Holger

PS: You perhaps recognized the pun in the headline. If not, you can read about it here: All your base are belong to us. Excuse my nerdishness 😉

PPS: One more for the German readers: Nerdish by nature 😇

ALL YOUR DATA ARE BELONG TO US

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.

The Credential Management API, enabled in Chrome 51, defined a framework for handling credentials that included semantics for creating, getting, and storing them The Web Authentication API […] allows web applications to create and use strong, cryptographically attested, and application-scoped credentials to strongly authenticate users. Also enabled by default are macOS’s TouchID and Android’s fingerprint sensor via Web Authentication. These allow developers to access biometric authenticators through the Credential Management API’s PublicKeyCredential type.

(Emphasis added by me)

The Web Authentication API draft from 12 September 2018 has a section on Privacy Considerations.

Biometric authenticators perform the biometric recognition internally in the authenticator - though for platform authenticators the biometric data might also be visible to the client, depending on the implementation. Biometric data is not revealed to the WebAuthn Relying Party; it is used only locally to perform user verification authorizing the creation and registration of, or authentication using, a public key credential. A malicious Relying Party therefore cannot discover the user’s personal identity via biometric data, and a security breach at a Relying Party cannot expose biometric data for an attacker to use for forging logins at other Relying Parties.

(Emphasis added by me)

… “depending on the implementation”… I use my fingerprints to access my laptop and used to use it for my phone. I trust Apple. This is my decision. I wouldn’t trust Chrome and web developers to keep my biometric data safe.

There is no point here. Today I have nothing clever to say. Only, I slightly worry what oversight there will be for this data. I know the draft says different, and it seems unlikely, but: When will we see the first headline in the news that a database for the website of StartupCo was breached and, among stolen the data, were some biometric datasets.

History shows that the more ways there are for things to go wrong, the surer it is that they go that way.

Keep safe.

You, Holger

PS: You perhaps recognized the pun in the headline. If not, you can read about it here: All your base are belong to us. Excuse my nerdishness 😉

PPS: One more for the German readers: Nerdish by nature 😇

AGAIN, WHY ARE WE DOING THIS?

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.

IT failures can also stunt economic growth and quality of life. Back in 1981, the U.S. Federal Aviation Administration began looking into upgrading its antiquated air-traffic-control system, but the effort to build a replacement soon became riddled with problems. By 1994, when the agency finally gave up on the project, the predicted cost had tripled, more than $2.6 billion had been spent, and the expected delivery date had slipped by several years. Every airplane passenger who is delayed because of gridlocked skyways still feels this cancellation; the cumulative economic impact of all those delays on just the U.S. airlines (never mind the passengers) approaches $50 billion.

Source: https://spectrum.ieee.org/computing/software/why-software-fails (Emphasis by me)

That’s $50 billion that could have been spent in another way. Now I cannot know what kinds of problems actually were present in this project. There are many different problems an IT project can suffer from. Projects of this size that fail, usually suffer from many of them at once.

Software development fundamentals are a big part. And these are a part you can control. So take every chance you get to improve at your craft. Here are some ideas for different skill levels.

For a junior/beginner:

• Design styles like object-oriented design and structured design
• Design patterns for organizing code
• Foundational design concepts like encapsulation, information hiding, dependency injection, modularity, composition vs. inheritance

For advanced / intermediates / professionals:

• approaches to memory management
• performance optimizations
• database design (advanced usage of unique attributes of your db)
• standards about internationalization
• UX and UI and how you as a developer can integrate that knowledge into your products

For seniors / experienced software engineers:

• Specifics and unique approaches to the domain you are working in (health industry, travel industry, manufacturing …)
• architectural designs patterns (layers, ports and adapters, SOA, multi-tier, publish-subscribe etc.) to be able to optimize for different qualities attributes like cost, performance, stability, security, maintainability etc.

Linting your code and making sure the code meets minimum standards is one step. And it’s a vital step. But the road is long and stony. (Sorry I had to write that 😇)

If you need assistance with any of these topics, reply to this letter and we figure it out.

Yours, Holger

AGAIN, WHY ARE WE DOING THIS?

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.

IT failures can also stunt economic growth and quality of life. Back in 1981, the U.S. Federal Aviation Administration began looking into upgrading its antiquated air-traffic-control system, but the effort to build a replacement soon became riddled with problems. By 1994, when the agency finally gave up on the project, the predicted cost had tripled, more than $2.6 billion had been spent, and the expected delivery date had slipped by several years. Every airplane passenger who is delayed because of gridlocked skyways still feels this cancellation; the cumulative economic impact of all those delays on just the U.S. airlines (never mind the passengers) approaches $50 billion.

Source: https://spectrum.ieee.org/computing/software/why-software-fails (Emphasis by me)

That’s $50 billion that could have been spent in another way. Now I cannot know what kinds of problems actually were present in this project. There are many different problems an IT project can suffer from. Projects of this size that fail, usually suffer from many of them at once.

Software development fundamentals are a big part. And these are a part you can control. So take every chance you get to improve at your craft. Here are some ideas for different skill levels.

For a junior/beginner:

• Design styles like object-oriented design and structured design
• Design patterns for organizing code
• Foundational design concepts like encapsulation, information hiding, dependency injection, modularity, composition vs. inheritance

For advanced / intermediates / professionals:

• approaches to memory management
• performance optimizations
• database design (advanced usage of unique attributes of your db)
• standards about internationalization
• UX and UI and how you as a developer can integrate that knowledge into your products

For seniors / experienced software engineers:

• Specifics and unique approaches to the domain you are working in (health industry, travel industry, manufacturing …)
• architectural designs patterns (layers, ports and adapters, SOA, multi-tier, publish-subscribe etc.) to be able to optimize for different qualities attributes like cost, performance, stability, security, maintainability etc.

Linting your code and making sure the code meets minimum standards is one step. And it’s a vital step. But the road is long and stony. (Sorry I had to write that 😇)

If you need assistance with any of these topics, reply to this letter and we figure it out.

Yours, Holger

ART

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.

Because my photography skills still lack, I try to read articles from professional photographers to get ideas and tips on how to improve. An article that made me think was about a photo-marathon in Munich (the article is in German). A photo-marathon is a one day event. You get multiple themes and have limited time to find a suitable picture for each. One thing I noticed was the photographer who wrote the article made sure to have a distinct visual language present in every photo he took: He cared for a hard horizontal line in the lower third of the image and wanted to only take pictures of architecture. His skills are on a very different level than mine but we both took the time and tried to think about what we want to show in our photographs and how to frame it. You could call it a style or a handwriting that your images show.

That made me wonder: When was the last time I really thought about my coding style and handwriting?

Thinking about my code handwriting means different things for me. On the one hand there are things like which programming language do I use. Do I write comments inline, do I write comments at all or do I let my code speak for itself with method and variable names that show their intent? But there are also fundamental decisions: How do I structure my applications, monolithically or modular? Do I refactor regularly? Do I use certain design patterns?

These are things that form my code handwriting and it’s no wonder that people who care about these things write them down in style guides. There are best practices that many people propagate that make your code handwriting easier to read and easier to understand – especially for people who aren’t used to your style. So please take care how you write your code and develop your beautiful and unique (code) handwriting.

This article could end here, but let’s turn back to our professional photographers. To the people who know the rules of composition inside and out. People who took many photos and know how to take them well. People how shoot photos intuitively that are a joy to look at. You know what some of these people do? They deliberately ignore all rules and create something that is truly unique and recognisable. In the eyes of the spectator that might not always be beautiful or even easy to look at, but it is art (at least that’s what they say) and it is their form to express themselves.

So let me end this article like this: Sometimes, to evolve your craft and find a new way, it is okay to ignore all or at least some rules when creating something. Software engineering is a creative, inventive and demanding art and you should take the time to question and ignore held beliefs when you create something. Don’t care about conventions or how other people might think about your work. Treat programming as the creative art form that it can be and deliberately go against some of your rules. Write a class with 300 lines of code and only one method. Name your variables a, b and c and don’t care what value they might have. Write a program that is just one big file or write something without line breaks. It will feel weird at first but I bet you’ll get a new perspective on things. And it never hurts to adjust your point of view. If you’d like some ideas have a look at these Github repositories. This is art.

rkh - almost-rackup

rkh - almost-sinatra

If you take a look at these examples you might wonder what they’re about. I did so as well. First I put it off, thinking this is nonsense and unnecessary. But I changed my mind. I would like to admit that I cannot really read that code. Looking at it makes little sense to me. It looks like code you’d expect a code uglifier to spit out. And then it hit me: I use uglifiers/minifiers on a daily basis to minify code for production use. But I never cared for how they work.

Maybe this is a thought and a style lesson. What does it take you to minify your code yourself? Do you get a deeper understanding from minifying code by hand? What does it teach you about your programming language? And what do you need to learn about your programming language to be able to minify your code by hand? Is minification deterministic?

I do not know. But I am intrigued to find out.

Yours, Holger

PS: This is an article I wrote 4 years ago on 02. Sept. 2014.

WHERE'S YOUR GPS

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!

Anyway, you get in your car and you begin to drive. Looking from your bedroom window, the direction of the house was more or less a bit to the left of the church and to the right of the shopping mall. So if you take your car and head in that direction then you are pretty sure that you will make it. Eventually, you just have to get there. How hard can it be?!

Midway through, the inevitable happens: You have no idea where you are, no idea where you have to go and you didn’t even bring fresh underwear because you packed nothing.

Would you go on a trip like that? I bet you don’t. At least not together with a partner or a friend. They would probably kill you. I would! 🤬

But why do software projects look like that? If you take a GPS that can reliably take you to a destination you’ve never been to before, you should use the “GPS” available for your software projects as well. That means specifications, risk and requirements management, architectural design documents, test set-ups and everything else that helps you on your way to your destination.

Otherwise, it’s just getting into your car without any idea of where you’re going.

Yours, Holger

THE FOUR TYPES OF DOCUMENTATION

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.

And they go on with this:

In this article I will explain how you can make your documentation better, not by working harder at it, but by doing it the right way. The right way is the easier way - easier to write, and easier to maintain.

There are some very simple principles that govern documentation that are very rarely if ever spelled out. They seem to be a secret, though they shouldn’t be.

If you can put these principles into practice, it will make your documentation better and your project, product or team more successful - that’s a promise.

Principles that make your project more successful (aka increase its quality)? Please tell me more!

The secret

Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing.

Perhaps I shouldn’t have told you the secret before you clicked the link? I don’t know. But if you want to learn something about how to improve your docs, do yourself and your readers a favor and read the article:

What nobody tells you about documentation

Yours, Holger

STARDOM (CONTINUED)

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.

I didn’t mention this in my letter, but it certainly is true. So I could reframe the question as: Who were your best teachers?

Matt Payne graciously shared three of his heroes:

Mary Rose Cook annotated-code.maryrosecook.com/space-inv…

Jessica Kerr twitter.com/jessitron

Katrina Owen for creating exercism.io/team and other wonderful things while being vocal!

And on the question why people sometime become heroes:

Because they are verbal.

So thank you to both of them. I already knew Katrina Owen but I didn’t know the other two. Bonus points for mentioning three women! 👍

Please send me more heroes and teachers.

Yours, Holger

STARDOM

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?

If so, why is that? Because constantly produce high-quality software (or products)? Or is it because they are very verbal? Some advanced the craft of software development and still do, so that might be a reason. But they just did their jobs, right?

I am really asking here… Do you have stars?

Yours, Holger

CODE QUALITY THROUGH HIGH-QUALITY DOCS

Hi friend.

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.

A beginner’s guide to writing documentation

The first thing should be this article from the resource “Write the docs” (a community of people who care about docs 😊 yes, that exists…): A beginner’s guide to writing documentation

This is a guide to documenting your first project. The first time is always the hardest, and I hope this guide will get you started down the righteous path. At the end, you should have a project that is ready for public release.

Who Writes the Docs?

Should all developers write docs as a matter of course? Is it even worthwhile having specialist writers? In this talk I’ll try to find some answers to these questions, based on my experience working in many teams - both in teams that have valued tech writing and in teams that haven’t. I’ll talk about the ‘documentarian’ mindset and how that contributes to better software, no matter what your job title is.

This is a video from a talk given by Beth Aitman at the Write the docs conf 2018 in Portland. So it’s rather recent.

I believe there shouldn’t be dedicated technical writers but that developers should write the docs. This helps in building empathy for the end users of our software.

Writing technical documentation when you aren’t a technical writer (series)

This series on Medium offers lots of insight on writing docs. The parts 1 + 2 from Taylor Barnett are a great start to get you going. It continues with documentation APIs. One important part of your docs.

Example API docs

These docs by Stripe are something like a (almost?) gold standard for docs. They are really good. Take example 😉

Alright that should be enough for a short introduction to your reading material. Queue it up in Instapaper/Pocket and let’s get better at writing docs.

Docs as code comments could be one of the next topics. Again, let me know what you think!

Yours, Holger

TEAMWORK

Hi friend.

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):

Whatever you are called is not as relevant as the identification with the type. The profile tool is an excellent way to build high functioning, happy team.

Once you know the people, you can optimize their jobs and roles for the organization with the side effect of happily employed people.

Obviously the core problem today is still that most bosses are not that competent - especially in the larger corporate entities. Unfortunately history has tended to favor the incumbents with the result that a lot of real talent is stifled.

Thanks Gary! I am reading a book about development practices right now. And this brought my thoughts back to this topic again: What types would make an ideal team of developers + manager?

So if you could design your optimal team, what types would you take (bonus points for the “why”)?

If enough answers come in, I’ll summarise.

Yours, Holger

PROCESSES FOR ACHIEVING QUALITY

Hi friend.

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.

The answer is as simple as complex: You need to find processes that help you achieve these results and then make sure that you—and everyone on your team—always follow these same steps.

This could mean that you use a service like Code Climate (I linked to them before) to test your team’s code against the same metrics on every commit / pull-request. The hard part for this process will probably be to find common rules for the code-metrics-tests. In a team I worked with, we did have some problems to come to a shared understanding which rules should be followed and which should be ignored. It starts with simple things like line length (always 100 cols, of course, right? Right?!? 🤓) and it continues with others like maximum length of a method, or module. And when are you allowed to ignore that rule, if ever?!

We debated about a day or more if my memory serves me right. Then we had found our rules. But this brought forth an even bigger problem: Get everyone to obey these rules… :fight:

Perhaps start with “simpler” (really?) things: Decide what your team should write in your projects' READMEs. Create a new wiki page (You know, these things from the 2000s. These days it’s all “shared knowledge base system thingy”) and write down, what the README needs to cover.

Then move to more contended territory: How to document your code. Will you use something like YARdocs? If so, which parts are required for every class/module? Which ones for methods? Decide and write it down so you can refer to it later on.

This should be a good start—and will take long enough. Believe me! Once you reached that point, we can talk about how to automate the checks for whether people follow your rules. And this would be something where I’d come in. This always takes precious time away from projects and managers have a hard time budgeting for that. If you need help in that area, write me an email. I can help.

Yours, Holger

QUALITY (CONTINUED)

Hi friend.

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.

(He doesn’t have to deal with creating software in the way that you and me might deal with it, but it’s applicable nonetheless.)

It is certainly true that taking into account the whole presentation of the library/product offers a good insight into what you can expect to get.

For software libraries that would mean your README, documentation and perhaps wiki pages, maintenance of your issue tracker and how you communicate with users of your library. Release schedule and notices of breaking changes together with your roadmap. These all help to get a better picture.

Do you have any other idea? How would you apply these thoughts on code from your co-workers? How do your measure their quality?

Yours, Holger

QUALITY

Hi friend.

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?

Consider the case that you are looking for an OSS library for your project. You find 3 contenders (often there are more, I know!). How do you know which one is best? If they offer demos, you’ll probably compare those, right? I know I would. I did it just yesterday. But if two are more or less equally good in fulfilling your use case, what would you do? Do you compare the source code? Good idea, I’d say. Feasible if the libs are small. Impractical for bigger ones. Alright, I believe what most of us do—perhaps even as a first step—is evaluating the library’s popularity! If more devs use library A then it will probably be better, right? Perhaps it’s written by someone you’ve heard of before? Even better! More credibility for this lib. But… did you look at the actual code? Do you have any (hard) metric for its quality?

There are tools you could use, like Code Climate and others. But they might only tell you half the story.

To get to the point: We do not have a reliable, universal way to judge code quality, and in essence our work. The only thing that comes close is peer review and your colleagues' judgment.

What do you think? How do you measure the quality of (your) work?

Yours, Holger

TRADE-OFFS

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.

The top three aspects that usually directly affect a software development project are

a) price b) quality c) speed

It is common knowledge between (project) managers that you cannot have all three of them. You can choose two at max, but the third will “suffer”.

I worked on teams that focussed on B. The projects cost enormous amounts of money and took literally forever. But they won awards. Tons of them. And the customers were happy. So that works.

Optimising for A and C is something I am familiar with as well. These can be quick prototyping projects. It also happens that these are full-blown client projects. Only, no one notices what they are optimising for. Everyone thought they focus on A only, but somehow are faster than necessary—perhaps because they are just really good at their jobs. And B is important to them as well, but somehow always loses to C. But not explicitly. It just happens that way. Because it isn’t a deliberate decision.

Make no mistake. Clients are happy if you are within the budget and on time. They are conditioned in a way that there are always bugs in software. It’s like a rule. So B usually just means that it works most of the time. For most cases. How it looks under the hood is of no interest to most clients.

If you want to have successful software projects you need to choose which aspects you care about and focus on. If you are good and fast, then it can make sense to have lower prices than your competitors, because you can complete more projects in the same amount of time. And earn more that way. But you have to make a deliberate decision about it and have everyone on the same page. Don’t just let it happen by accident.

Yours, Holger

LAZYGIT

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.

Today I tried out Lazygit. I believe I found it in the Hacker Newsletter or something similar. It just might be something like the best of both worlds. Just wanted to really quickly share that with you.

Yours, Holger

PS: Yes it really is a nerdy tool. And it looks cool and is a nice encouragement to actually learn Go and send some pull requests.

WHAT AM I DOING?

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?

For a few years now I ran a small/tiny SaaS for German companies doing telesales. I have prior experience as I worked in this industry for 6 years during university. So I created the application to do telesales. It was designed and developed to support the telesales marketer in the right way. The way I always wanted to be supported while calling companies (strictly B2B! 😚). I will close that company towards the end of the year. I just do not have any interest in it anymore. You do need a certain amount of passion and interest in the market and the topic if you want to have some success marketing your product. I lack both these days.

I will concentrate all my energy into my freelancing business, which I want to turn into a consulting business. Or something else. I am unsure. I have some ideas how to evolve this but I am uncertain which one is the best direction.

Which brings me to you! You have been reading my emails for the last few weeks, and you signed up for the newsletter some months or years before. Because you read something I wrote that you found interesting, I guess. I am good at sharing knowledge, helping people learn and supporting developers in growing their skills. I had this wonderful experience last week: A former co-worker wrote me an email congratulating us on the baby. She also gave me the big compliment, that during her time with me she learned more than ever before or after. She was “my” intern and I tried to enable her to grow according to her talent. It seems I did it quite well. I received compliments like that rather frequently. I am wondering whether I should pursue this path with more intensity…

My current contract ends on September 30th. I am now in talks with companies about the time from October 1st and will have interviews later this week. This is quite a long shot, but if you or your company is looking for a senior developer for who could mentor you or your team, please get in touch. I’d love to talk about ideas how I could support you. Things like mentoring, but also vetting/hiring developers, giving workshops, doing code reviews. If anything like that sounds interesting, please answer this mail. To be clear: I do not seek permanent employment. 😄

I am curious what you think. If you don’t have anything in mind, I’d like to ask something else of you: Please help me find other readers. You know someone who could find my emails entertaining. Someone on your dev team or a friend? Please send them to my website www.holgerfrohloff.de and make them sign up 😉. It means a lot to me and supports me.

Thank you.

Yours, Holger

DAYLIGHT SAVING TIME

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?

What about already recorded time like a created_at or updated_at timestamp? Do we keep the old offset and have to also keep around when it was recorded? Because up until a certain date these offsets were still valid, and after the date these aren’t valid/possible anymore?

DST exists in the US as well, I believe. I guess they could abandon it as well, once Europe does it. This would be an interesting time (pardon the pun).

Timezones and handling time is always something that has to be handled with care, but having big changes like abandoning DST really makes it interesting.

I am interested to hear what you think about the implications of abandoning DST.

Yours, Holger

YOU GET TO DECIDE

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…

This made me again realise how great your and my job are. We get to do what we love. We can be creative, get lost in the details and sometimes even improve the world—if just a tiny bit.

Or we can do bad and support totalitarian governments, implement censored search engines and track people‘s behaviours.

It‘s up to you to decide what to do with your gift.

Yours, Holger

THE INNER-PLATFORM EFFECT

“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.

He starts with the Inner platform effect. This is an anti-pattern I did now know before but was able to recognize once I read his explanation and examples.

What about you? Can you find examples for it? Tell me about them!

You can read his article here.

Yours, Holger

WHY ARE OUR ESTIMATES OFF, ALWAYS?

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.

In the end, we did manage to complete a lot of work. But these were only the first batch of scheduled tickets. We couldn’t fully complete those even! How could it be that we were so much off with our estimates? No harm was done and we are still really good on time, but it was strange.

In this light, please enjoy this oldie/goldie about project estimates… Why are software development task estimations regularly off by a factor of 2-3?

What are your experiences giving estimates?

Yours, Holger

FORMATTING DATES

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.

What I did not run into (because of my luck working with Ruby and JS) is the nice little thing, Peter Hosey describes in his article “Unicode date formats, YYYY?!". You should click that link, if only just to see the url of the article. It’s not the title I’ve mentioned above…

Short summary: There is this thing called “year for week-of-year”. You probably know that sometimes at the end of the year the calendar week 1 already started—but we’re still in the old year. If you print a date of that range, say December 31st 2018, you have to pay attention how your date-formatter-function actually formats the date. If you use the wrong pattern, you could end up with the wrong year!

Go ahead and click the link “Unicode date formats, YYYY?!" 😉

Happy 2018!

Yours, Holger

PS: If you want to display the year for week-of-year in Ruby/Rails, you’ll need to use the pattern %G or %g:

ISO 8601 week-based year and week number:
The week 1 of YYYY starts with a Monday and includes YYYY-01-04.
The days in the year before the first week are in the last week of
the previous year.
  %G - The week-based year
  %g - The last 2 digits of the week-based year (00..99)
  %V - Week number of the week-based year (01..53)

READING CODE

_ 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:

Most programmers agree that we don’t read enough code. The interviews in Peter Seibel’s book, “Coders at work” highlight a comical contradiction: almost all the programmers interviewed by Seibel recommend that others read code for fun, but none of them routinely do so themselves.

This is the opening paragraph of a post by Stephen Malina titled Reading Code. Please click that link and read that post. It will leave you thinking. I promise.

Yours, Holger

SURPRISES WHEN STARTING OUT AS A SOFTWARE DEVELOPER

_ 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.

Today I want to link you to Henrik Warne’s blog where he tells us about a few surprises he had when starting as a software developer earlier in his career.

I will get back to this topic and talk about mine, once things are back to “normal” here.

Yours, Holger

BIG NERD RANCH

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.

As a Product Manager, developing a deep understanding of the root problem is critical to helping you save time and money before writing code. On the rare (cough) occasion these things happen, it’s important to have processes in place for you to evaluate and prioritize these problems for your team quickly.

I know not everyone of you is a developer. And it makes sense to broaden one’s point of view. So please enjoy this article from Big Nerd Ranch blog

Yours, Holger

LIVABLE CODE

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?

According to Mei, in order to be “livable”, the organization of a software system should lie somewhere between the extremes of the horrific tangled mess of code hoarders, and the antiseptic cleanliness seen in the pages of interior decorating magazines and home sales brochures.

This is not something I had considered or expressed before; though it has always been something I’ve sheepishly practiced.

Can a system be too clean? Is it possible to focus so much on cleanliness that no one can practically work in the system?

In this article Robert references a talk by Sarah Mei that he saw and shares his point of view. Have a read.

Yours, Holger

MY AUTOMATED PUBLISHING WORKFLOW

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.

Writing the article

The first thing to do is to write my article/email. This is where it all starts, and this is what I look forward to doing. Writing happens for me in the application Ulysses. I used to write in other apps like Simplenote, IA writer or more long-form in Scrivener. For a few months now, I use Ulysses exclusively for all my writing and notes. It feels good to have everything in one place and not scattered throughout more apps.

I write in Markdown. All the time. I just got used to it over the years and I like the simplicity. Of course that comes in handy when writing Issues, Pull Requests, Wiki entries or Readme for GitHub powered repositories. Since GitHub uses (or supports) Markdown for all these, I can easily write for that. So if you never really got into Markdown, I can really suggest trying it out some more.

I start my articles with the date of the current day or the date when I plan to publish the article. Sometimes I write a few days in advance—if I know I won’t get around to doing it on the day in question. The next line will hold the title. I mention it in this detail because it’s important in a later step. Then the body of the article will begin.

I aim for a length of about 2 minutes reading time. Earlier in my career I wrote really long articles (like this one 😉). But I noticed that people tend to not want to read such long articles. And since I write every week-day, I try to keep it short and on-point. This is usually harder than it sounds. Ulysses helps me reach the 2-minutes-marker with a visualisation of the goal.

Once I am done with the article, it’s time to proof-read.

Then on to

Publishing the article

I use Jekyll a static site generator for my website. I used to use Wordpress but I didn’t really use Wordpress and the constant necessity for updates was annoying. Also I do not use PHP and have little experience. So I was always dependent on external themes and plugins for anything. But I wanted to be able to develop/hack on my own website. Since I do know Ruby very well it made absolute sense to use that as my website technology. Hosting is done via GitHub pages. So that’s one more thing I do not have to worry about. The hosting, the SSL certificate and all “updates” are handled by GitHub. Of course updates to Jekyll are made by me. GitHub offers security monitoring for repositories, so I am always aware if a dependency it outdated or has a leak. Another convenience is the ubiquity of GitHub. It’s available in many automation tools' stacks, so I can easily use it if needed.

To publish my article, I use my iPad. I love the iPad’s form factor (it’s a 12.9"), the tactility and using it. I look for ways to use it more. With the apps Workflow, Drafts and Working Copy I have everything I need.

Breakdown of the steps for publishing

To have a new article published with Jekyll, I need to do the following things. I used to do them manually:

0. Write in Ulysses
1. Create a new file in site/_posts folder with the naming convention _posts/${year-month-day}-this-is-the-title.markdown
2. Format the front matter (configuration for this specific post/article in YAML) with
   • date
   • title
   • layout
   • categories
3. Insert the contents of the article from Ulysses
4. Commit the file/changes
5. Push to origin/master

The first two steps involved more work than I’d like to do for publishing. After automating this process, this is the remaining procedure:

0. Write in Ulysses
1. In Ulysses: Sharing -> “Preview in Text/Markdown” -> … -> “Open in another application”
2. Tap “Drafts” (version 5, it might also work in version 4), then in the Drafts-layer tap “Open”
3. Inside Drafts, I access my “Publish article to www.holgerfrohloff.de” action

The rest happens automatically and I am left with an open Safari browser tab pointing at my website.

Another thing that happens: IFTTT watches my site’s RSS feed and publishes new articles to LinkedIn automatically.

At the end I show ideas for further reducing the amount of steps that I will probably explore.

The Workflow workflow

Before going into the actions for Drafts, I want to make a quick detour to Workflow.app. Using Workflow is actually the very first step that happens in the Draft action and I want to show what I am doing there.

As you saw in the original procedure in step 1, I needed to create a file with the title of the article as part of the filename. In Rails you call this a parameterized string. Workflow creates it for me:

It gets the document’s title as input. This is the first line in a Drafts document. It returns the parameterized title. I will then use that output inside an action in Drafts.

The Drafts actions

I actually have and use three Drafts actions:

• Publish article to www.holgerfrohloff.de (the main one I manually start)
• Commit-in-Working-Copy
• Push-in-Working-Copy

The latter ones are run by the first one. While experimenting and trying to make it work I ran into a problem with Drafts, that I didn’t know how to get around: I could not chain two x-callback-url action steps. If you do not know what x-callback-urls are, I will get to that in a minute. I researched how other solved that, and stumbled upon this article Automating iOS: A Comprehensive Guide to URL Schemes and Drafts Actions. It’s from 2014 and targets Drafts 4 (the previous version), but the concepts still somehow applied to my problems. The author presents the necessary workaround: Use an x-success x-callback-url to call another Action in Drafts, with the runAction action. Puh. Here’s the docs from Drafts.

What happens is essentially this: Once the action is finished it returns to Drafts (specified so in the x-success callback) and executes the action runAction with its given parameters. In URL this looks like this:

working-copy://x-callback-url/commit/?repo={{5minpause.github.io}}&limit={{3}}&message={{broadcast}}&key={{secret-key}}&x-success=drafts5%3A%2F%2Fx-callback-url%2FrunAction%3Ftext%3D%26action%3DPush-in-Working-Copy%26allowEmpty%3Dtrue

The start is the x-callback-url for Working copy app. I execute the commit action on the repo 5minpause.github.io (my website) with the limit of 3 (only changes with three files get committed) a message that serves as the commit message and the secret key needed to do this at all via x-callback-url. This is a requirement and safety mechanism by Working Copy. The value passed to the x-success parameter is url-encoded. This is needed for Drafts to be able to run it. Without encoding it would look like this: drafts5://x-callback-url/runAction?text=&action=Push-in-Working-Copy&allowEmpty=true

Again, drafts://x-callback-url/runAction just opens Drafts and tells it to use the runAction action. The param text is left empty (but it is required!). You could specify text to be included in your document (that is created as part of the action). I do not need that. action has the name of the Action I want to run in Drafts. You noticed, that is the name of one of my actions from above. The last param allowEmpty=true is decisive. It allows me to leave the text blank and essentially leads to the action being executed just on any document that happens to be active in Drafts. Since the “Push in Working Copy” action is document-agnostic that’s exactly what I want.

But this was already the last step in the chain. I used that because it was easier to describe. The first step actually looks like this:

working-copy://x-callback-url/write/?repo={{5minpause.github.io}}&path={{_posts/}}[[date]]-[[workflow_result]].markdown&text=---%0a{{layout: post}}%0a{{title: "}}[[title]]{{"}}%0a{{categories: "newsletter"}}%0a{{date: }}[[date]]{{ 15:00:00 +0200}}%0a---%0a[[body]]&key={{secret-key}}&x-success=drafts5%3A%2F%2Fx-callback-url%2FrunAction%3Ftext%3D%26action%3DCommit-in-Working-Copy%26allowEmpty%3Dtrue

It starts with Working Copy and the write action. I specify the path. Notice the [[date]] value. This is Drafts-magic, as it automatically replaces/interprets certain values in the URL. The other one is [[workflow_result]] that is provided by an earlier action step in this action, the Workflow “parameterize text” workflow. The value for the text param is the contents of the document. It starts with the YAML front matter. Everything written in {{ }} is put like that into the document, including spaces, without escaping/interpreting it. %0a means line-break. At the end you see the “Commit in Working Copy” action being called as x-success parameter.

The last step is opening the Safari browser at https://www.holgerfrohloff.de and that is simply another x-success={{https://www.holgerfrohloff.de}} parameter. Since Safari is registered as the receiving app for http/https protocols, it gets used to open that URL.

And that’s the thing about x-callback-urls. There is probably a lot to say about it, but the essence is that apps can register for a certain protocol. Working copy registered for the protocol working-copy://, Drafts for drafts5://. Numerous other apps offer this as well. This website offers the spec for app authors to implement and shows a comprehensive list of x-callback-urls for different apps.

This is how it looks on my iPad:

Automating publishing to a Jekyll website using iOS

I have some ideas/things I’d like to try out:

• Automating the removal of the date. If you looked at the video, you saw that I manually remove the date from the beginning of the article. This could be automated.
• Wrap everything into a workflow that I can access/start from the share sheet on iOS. This would essentially remove everything after Ulysses. I would only need to call the action from the share sheet in Ulysses and I would be done.
• Try to improve usage of callback-urls in Drafts. While searching for ways to chain actions in Drafts, I created a topic on the forums: https://forums.getdrafts.com/t/chaining-x-callback-urls-does-not-work-as-expected/2157/2. The support then pointed out that using Call URL action steps might not be the optimal way. I should change those to use the Call Callback-URL action steps inside Drafts.
• Support drafting of articles. Sometimes I write these articles a few days in advance. I cannot, currently, publish them without running through the pushing to origin/master step.

The big thing remaining is publishing to Drip. Since I use Drip to send these articles as newsletters to my readers, I have to create the on their website and schedule them. Drip offers a REST API that I could probably use from within Workflow app. An alternative would be to use Zapier to create these POST requests after pushing to GitHub. That might also work.

BOOKS I ENJOYED READING

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.

Principles by Ray Dalio

I mentioned the book before in one of my emails. Reading this book I had the feeling of finding something that speaks to me, more than once. The situation like there was a light bulb lighting up, because you see connections between things you were blind to, before. I know I’ll re-read that book a few times, because I am certain that there are more lightbulbs hidden in it.

Confident Ruby by Avdi Grimm

I read the book too early in my career. I wasn’t ready for it. I put it down. A few years later somehow I remembered it, perhaps I found the ebook on my computer somewhere. I started reading it again. And I couldn’t put it down. Please let me quote from its website, because I definitely couldn’t put it any better:

Confident Ruby is, first and foremost, a book about joy. It’s about the joy I found when I first discovered how elegantly and succinctly I could state problems in Ruby code. It’s about the joy I gradually lost as the “real world” snuck in and cluttered my code with distracting edge case scenarios, error handling, and checks for nil. And it’s about how I came to recapture that joy, by employing small patterns and stylistic choices to make each method tell a coherent story.

Sapiens by Yuval Noah Harari

I picked this up in a book store on Gatwick airport near London. I was heading home from the Isle of Ruby conference and I felt like I should buy a book. It was marketed as a bestseller on some list. Usually I do not pick up books like that. But something made me take it. Perhaps it was Bill Gate’s quotes on the back?

“I would recommend this book to anyone interested in a fun, engaging look at early human history…you’ll have a hard time putting it down.” (Bill Gates)

I honestly don’t know. But I am glad I picked it. I read most of it laying at the pool on Rhodes island. It’s not heavy literature. But it’s a fun read if you are looking for something during the summer. It does answer several questions I didn’t formulate for myself before. Like, how religion evolved and what came before it. Sure there’s the bible, Qur’an, Torah and other texts but did people believe before that? And how did sapiens spread across the world?

Deep Work by Cal Newport

I read that over a year ago. Open office floor plans and their negative impact are discussed a lot these days. An important part of the discussion is people’s inability to concentrate on their work in an open office with many co-workers. This books doesn’t really talk about that. It talks about the opposite of that. It shows you how establishing a deep work ethic helps you produce better results and do more intense work—during your working hours. The author shows you 4 rules you could/should follow to reach a new height of productivity and just work better. While it’s sometimes a bit too much and he takes things a bit too seriously, I honestly applaud the idea behind it. Finding the focus to work better and more concentrated does help me and perhaps that’s something for you as well.

Alright. Are you disappointed because you expected more programming or software development focused books? Ok, then I’ll give you two more of those: Anything by Sandi Metz Both books are great and applicable even if you don’t work with Ruby. They just use Ruby as a simple, accessible example language. But in their essence they teach you the most important aspects of object-oriented software development.

In case you do like one of these books or especially if you completely disagree with me on something, please tell me by responding to this email. And if you have any book recommendations you’d like to share, please also tell me.

Yours, Holger

MAINTENANCE AND JANITORIAL ACTIVITIES

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.

Do you know that feeling? I hope 🤞 you don’t experience that too often. But that’s what I felt the other day when I had to look into an older code base that I worked with a while ago. These are the distinctive characteristics of a code base that wasn’t looked after enough. A code base where refactorings did not happen consistently. Where technical debt was piled sky high and where things were just left how they always were. Because the cost of cleaning up was thought to be too high.

This is what happens, if a team doesn’t have a policy they consistently follow. Every team needs that policy and it’s name is something like this: “Clean up your own mess and clean up anybody else’s. And avoid making a mess in the first place.” Admittedly that’s a bit clunky. 😂 But still. You have to make regular refactorings. Usually the best point in time is, when you reached a new understanding of the business case that you are replicating in your software. When you are writing code you have a certain knowledge about the thing your are building. And this knowledge evolves and grows over time. It’s common to look back at code and notice that the application has outgrown the old code.

Example: We have Companys in our application. When we want to import new data into the app, somebody (who’s authorised, but that’s another story 😉) sends an email to a certain email address with e.g. an Excel sheet attached. Whe then parse the sheet and import the data into the app. But only, if the email address is known. How do you test if an email is known? We created an EmailAddress model and set things up in a way, that a Company can have many EmailAddresses. That way we could be certain that different people of the company in question could initiate imports, but we didn’t need to know who it was in the specific case. Later on we noticed that the companies usually have email addresses with the same domain. It did not happen at all, that employees of a company had email addresses with different domains. So we deleted the whole email address model and all records in the database. And we created a new attribute for the Company model: domain (of type string). So now we only check the domain (and tld) of the email and can see if it’s whitelisted.

Simple example? True. But image what that picture could look like if we just added a domain attribute without deleting the EmailAddress and the association. People wouldn’t know what they were supposed to use, or which would precede the other.

So cleaning up makes sense. With that in mind, look through your code base. What old entities, things or concepts should you rework, delete or improve on?

Yours, Holger

PS: Another thing you should clean up? Your mom would probably say “your room”. But what about your OAuth authorisations for apps you tried out but don’t use anymore? Have a look at Twitter, Github and other providers you might have used earlier. Some people use this thing called Facebook, I hear. Perhaps you used it to log into things?

PREMATURE OPTIMIZATION

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! 😉).

Now that the project “door bell” is off the table, I had to connect the underground power cable for the gate again. Which, in the meantime, was missing a bit in the middle, where I made the cut. So I couldn’t just put it together anymore. I needed to insert a new piece of underground cable and connect everything on two sides. Here’s where today’s title fits perfectly: When connecting two cables with a new self-cut cable in the middle. DO NOT, I repeat, DO NOT estimate the needed cable length before connecting the pieces. Just use something that is way longer than you need. Do not try to half-measure everything so it’s just perfect. Otherwise you might be as “lucky” as me: The self-cut piece of cable for connecting everything was too short. Of course I noticed this after I already connected 3 of the four parts, and only had the last part remaining. Did I mention before, that it was already dark outside and the mosquitos swarming around me—squatting and sweating there—with my pregnant wife sitting next to me holding a flashlight, so I could see while holding my face near the soil just to be able to screw the connection-screws into the connection thingy? WTF. The thing was, we needed the gate to be operational so we had the safety of being able to drive the car. Because my wife could give birth now any moment and we need to be in a hospital for that… 🎉

So, enough off my stories. To bring this around to software development: Once again, trying to optimise things before you have the complete picture of the situation, might not lead you to victory and success, but to soil on your face, mosquito bites on your whole body and more swear words than I’d like our daughters to hear. Take care.

Yours, Holger

SPAGHETTI WIRINGS NO-ONE KNEW ABOUT

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.

So… how hard can it be?! (Queue picture of Jeremy Clarkson here, before he got old and rich 😉)

Turns out, we spent large parts of Saturday and the whole of Sunday, more than 8 hours, and achieved nothing. We got the help of my father-in-law as well. He lived in this house before we bought it from my parents-in-law, so he knows his way around the conduits and everything. But! somehow somewhere there are some electrical conduits lying underground here, no-one knows where they are, how they are connected and frankly, how some things are even working at all in the house/garden. Because everything is a mess. Image a junior developer trying to build a complex system that gets things patched onto from other juniors. Then along comes an intermediate trying to improve things, without fixing the underlying mess. Well perhaps you have an idea in your head how it might feel to operate in such an environment. It’s a horror show.

I haven’t felt so much frustration in a long time. One thought lingered in my head throughout the weekend: If only there was some documentation about this electrical chaos! Back, when this house was built and the wiring installed, and than patched onto, and things were modified, the people responsible…well they probably didn’t think much about documenting stuff. Because it was all in their heads, and fresh and “they knew what they did”. But nobody thought about 20 years down the road, when no-one remembered anything. We could have easily installed everything and worked around all the edge cases if only we had some written (or painted, or recorded — I’d take anything by now) documentation.

In my job I am lucky to build applications and software for my clients. The documentation usually revolves around elaborate ReadMes, Wiki texts and images. 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.

What about you? Do you regularly document? Would you mind sharing your horror stories about incidents where docs where missing and you severely felt it?

Yours, Holger

PS: Did you do some weekend programming, some Katas or somethings different? I came across this resource after already writing to you: https://programmingpraxis.com/

LET'S PRACTICE TOGETHER

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”.

Just a short detour what that’s about: I have my website at holgerfrohloff.de and it’s built using Jekyll, a static site generator. I write my newsletters on my Mac or iPad (or sometimes iPhone). I want my writing to appear as an email, sent to you. But it also should appear on my website, without me having to copy and paste markdown files, commit them and deploy it. Then it should ideally be distributed to LinkedIn, Xing (that’s a German LinkedIn 😉) and perhaps Twitter. All automatically. I am building this with three iOS apps and a bit of IFTTT and perhaps Zapier. I’ll tell you about it in detail once it’s finished. It’s a lot of fun for me.

Now to what I wanted to tell you about in this email: I love to have small projects like that. Projects where I can tinker and explore at my one pace. Where I do not have to keep track of the hours spent and where I can just have fun. I believe projects like that keep my relationship with coding healthy, because I can enjoy other sides of the profession as well. I also believe that you might benefit from having small projects yourself. Michael Tsai wrote about Kindling projects in 2015. But it’s still relevant. A small step into this direction (because not everyone might have a project at hand) could be Code Katas:

How do you get to be a great musician? It helps to know the theory, and to understand the mechanics of your instrument. It helps to have talent. But ultimately, greatness comes from practicing; applying the theory over and over again, using feedback to get better every time. But in the software industry we take developers trained in the theory and throw them straight in to the deep-end, working on a project. It’s like taking a group of fit kids and telling them that they have four quarters to beat the Redskins (hey, we manage by objectives, right?). In software we do our practicing on the job, and that’s why we make mistakes on the job. We need to find ways of splitting the practice from the profession. We need practice sessions.

Have a look around at the website (linked above). Perhaps that’s something you’ll try over the weekend? Anyway, have a great one!

THE BULLSHIT WEB AND OUR RESPONSIBILITY

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.

At the time, a few of my friends were getting cable internet. It was remarkable seeing the same pages load in just a few seconds, and I remember thinking about the kinds of the possibilities that would open up as the web kept getting faster.

And faster it got, of course. When I moved into my own apartment several years ago, I got to pick my plan and chose a massive fifty megabit per second broadband connection, which I have since upgraded.

So, with an internet connection faster than I could have thought possible in the late 1990s, what’s the score now? A story at the Hill took over nine seconds to load; at Politico, seventeen seconds; at CNN, over thirty seconds. This is the bullshit web.

Do you also build products and things for and on the internet, like me? I do not necessarily want to make quoting people a regular thing here, but the article “The Bullshit Web” makes the rounds on the internet these days. And it spoke to me. You see I do build websites and web apps. And I built them for bigger corporations. And integrating trackers and ad-networks and all this nasty things that slow down the web-experience for our users and makes the web slow and bad…well I included some of them during the last years. Of course it seems like it isn’t always easy to say no to requests like that. The executives of your clients want to have these things, because that’s what their “business models” forces upon them. And most of the times, if you don’t include them, somebody else will. Perhaps you risk the well-being of your employer and the other employees, if you do not do that. Because BigCorp™ will just go somewhere else instead. But perhaps we’ll have to find a way. At least in Germany right now, the market for developers is a sellers-market. That means we as developers can almost freely choose where we want to work. Everybody is looking to hire new devs, the salaries went through the roof and it’s easy to find new work if you accept the many recruiters' offers. So losing your job might be possible, and it’s a hassle to have a new one even if finding one is easy — I know. And still. If anybody has the means to change things and habits like that, it’s us as developers. Along with the companies we work at and the colleagues we work with. I know I am a bit idealistic, I was with the GDPR before, and I am again now.

When discussing with clients who want to have all these trackers and beacons… I was thinking about how one could argue that getting rid of them is in their best interest. One thought that came to my mind is, that these models aren’t as successful for (e.g.) newspaper companies, as they’d like them to be. A few of them (New York Time for example) try to make a subscription model work. You pay them a monthly or yearly price and get access to more content. I believe that users are more willing to pay if their experience is better, I they enjoy the product more than the alternative of not having it. And their target audience is people who value quality-news enough that they are willing to pay for it. And they have the choice between many on-surface similar offers. Couldn’t an offer that separates itself from the others because it values the user’s experience, the speed of the offering, the low barrier for entry, the usability for disabled users more than anything else? Doesn’t a crowd, that’s composed of these millions of users, who stand behind this description I just made, look large enough to be able to finance an online-venture like that?

I am not sure. But I’d like to find out if it’s possible. And that starts with saying no to requests for trackers, beacons, advertisement-networks etc and offering an alternative and a healthy discussion about the pros and cons.

With my clients, I’ll certainly do that even more now. So thanks for the article and the initiative, Nick Heer.

What will you do? Do you care about that?

WHEN DO YOU KNOW ENOUGH?

“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.

As I already told you, I am an Architect personality. One of my traits is the constant urge to improve, to learn more and to get better. So my impulsive answer to this question is “never”. This is only half the truth though. Of course it reads better if I tell you that I never stop learning. But it would be a lie.

I’ve worked as a professional software developer for over 10 years now. I started as a novice, not even junior level, developer. I learned and evolved into a senior and now I am at a level where I can work as an independent consultant with my clients. I thought about going back to university to get a Master’s degree. But I do not want to. I believe the trade-offs are not worth it for me. I am glad I do not need to sit somewhere anymore and learn or absorb some knowledge from someone.

That said, just yesterday I had to research something with testing async functions in my Redux action creators. I use fetch for querying the API, and wanted to test the action creator that dispatches the other actions.

(This is the code I wanted to test, but simplified)

export const fetchApiData = (productId, params = {}) => {
  return (dispatch) => {
	dispatch(requestApiData(productId))
	const url = `/api/v2/products/${productId}`
return fetch(url, { credentials: 'include' })
  .then(response => response.json())
  .then((json) => {
	dispatch(requestApiDataSuccess(productId, json))
  })
  .catch((error) => {
	dispatch(requestApiDataFailure(productId, error))
  })

}
}

The test was supposed to make sure, that the correct action was dispatched on success and on failure. But I have to admit I couldn’t do it. I spent around 2 hours trying to use the library fetch-mock like in their example. But my BabelJS setup wasn’t able to transpile the code. So async and await always produced syntax errors. Node v6 just can’t handle them properly. I tried different plugins and presets for Babel always without success. If Google offers it as a solution and if StackOverflow says to try it like that, I did… In the end I postponed this and will try to debug it with a colleague once he comes back from vacations. I read, I learned, I tinkered, I tried. But with no success. Just a lot of frustrations.

So to answer to initial question: In our field we never really stop learning. We might pause for weeks or perhaps sometimes months at a time, where we just use our knowledge to create things. But in the end there will always be problems and tasks where we must learn something new.

That’s one to the things I love about my work. Do you have similar experiences?

Holger

PS: If you happen to know a solution for my Redux problem or have sample code that I can adjust, please don’t hesitate to share it. 😉

PROFESSIONALISM

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.

This feeling when you’re worried about something mostly out of your control… feeling helpless. And then the doctors and midwifes help you and take care of you… This is a very strong feeling and emotion. The professionalism that they show in calming you down and making sure you’re alright.

If you ask me, that’s what I aim for with my clients. They don’t have to worry about our project, because I am there and taking care of everything. That’s my mantra.

What’s yours?

THE 4-DAY WORKWEEK

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.

This experiment was studied by two researchers, one of them said:

They worked out where they were wasting time and worked smarter, not harder […]

There are so many interesting takeaways from this article. I will definitely come back to it and talk about topics like billing time for work done (a topic of interest to me as I am working as a freelancer since January) and finding motivation and smart-working.

For today I would like to think about the topic productivity. How can I do more work in less time? My wife will give birth to our second child in a few days. As a result I will reduce my billable time by quite a lot, to have more time available to spend with the family. Still I want to be able to charge my clients enough money so I do not experience a drastic cut in revenue. So this makes me look for ways how I can be more productive. If you want to improve some condition, you need to measure it. Otherwise you don’t have any way to find out which actions improve your condition and which worsen it. So now the question is: How do you measure your productivity, when you are writing code, creating features, delivering software (pieces) to your client? One simple, almost obvious, measure might be how much you code. So this could be the lines of code, that you are producing. I feel like this might be a delusive metric though. I like brevity. I do not favour brevity over explicitness/clarity, but I try to write less code. In the sense of coding smarter, not harder. Equaling more code with more productivity makes no sense for me in that way.

I also like to commit early and often. My commits are usually small and concise. In so far it could be a metric to count my commits. Now I think I could increase my productivity by committing even more. Without changing anything else! It would also put others in a bad situation, if they just happen to commit less, with bigger commits. Regardless of whether I’d like that way of committing, they would appear to be less productive than me, even if the weren’t. I guess counting commits does not make any sense then, for me.

Then I thought of another metric: The number of opened pull requests. I believe, now we are getting somewhere. Every open pull request tries to improve the status quo of the software. It could be a new feature, or just an addition. It could be bugfixes. It would be work-in-progress branches or just spike solutions where things are tried out. But every new pull request you open shows that you did real work, for the benefit of the project. So I do hope your team is doing pull requests, and I do hope you have a good review process. Because I think this really is a nice metric of productivity. Perhaps we should only count merged pull requests, not opened pull requests? Because a merged PR shows that your changes were accepted and really brought the project forward.

I do not have a better metric to measure my productivity than merged pull requests. I think it’s still not the perfect metric—what happens if your team partners are on vacation, or sick and the review process hangs? This makes your PRs stale… But this metric will be the one I’ll keep an eye on during the next few weeks. For now I’ll just count the PRs by hand and keep track of them in a spreadsheet. If it turns out to work well enough for me, I might use GitHub’s API to automate that.

Please tell me about your metrics. How would you track your productivity? Perhaps you already do?

Holger

SORRY TO SAY, BUT YOU’VE BEEN HACKED

Please excuse this email’s subject line. Did you receive an email like that before? As I wrote a few days ago, I did.

More than a few times. That’s why I see that I use two-factor authentication for every service that offers it. If you do not know U2F (Universal two factor), this means that after providing a service with your login and password, you’ll also need to provide a one-time password (OTP) from a trusted source. This makes hacking into your accounts (for instance through social engineering) way harder. The OTP usually is in your hands and cannot be easily stolen, since this OTP only has a lifetime of a few seconds. Afterwards it’s invalid and a new one is needed.

This works because you can have an app on your phone, that presents you these OTP for your different accounts. This is the way I have done it the last few years.

• Navigate to website or open an app
• Use Password-Manager integration of my OS to access my credentials
• Paste credentials and confirm
• Open app on phone (Google Authenticator) that presents me the OTP
• Copy and paste the OTP into the form field
• Access my account

Well, it’s no wonder only few people use that! It’s a hassle and no fun.

Ok, but there’s a better way. I always try to do things better and more efficiently. And this process surely needed some improvements. What can I say, they were there all along, I just didn’t know! There are hardware devices that can act as your U2F and provide you with the OTP right on time. They come as USB, USB-C and NFC compatible devices (not all in one, though). They can be used with your computer and with your phone (through NFC even with new iPhones). Chrome supports these devices for a few years already. Firefox does support them as well, although you have to enable it yourself!

The steps now look like this:

• Navigate to website or open an app
• Use Password-Manager integration of my OS to access my credentials
• Paste credentials and confirm
• Tap hardware usb key and have it automatically enter and confirm my OTP
• Access my account

Ok, but there’s an even better way! 🤓 I do use 1Password as my password manager (and you should too!). 1Password supports OTP-fields when entering credentials. You can scan the barcode using 1Password when setting everything up. Now 1Password completely takes over the second factor:

• Navigate to website or open an app
• Use Password-Manager integration of my OS to access my credentials
• Paste credentials and confirm
• 1Password automatically copies the OTP to my clipboard and
• I just paste and confirm again
• Access my account

While this seems like on step more than the hardware key thing, I do like it very much. It syncs across your device, works on all OS’s and you don’t have to fiddle with a small USB/NFC device. You can’t forget it somewhere, because that would endanger your accounts very much…

The U2F devices have other benefits as well though: You can use them to sign your Git commits with them to make it cryptographically unfeasible to tamper with them. This shows as “signed commits” on GitHub.

If 1Password isn’t your thing, there are other managers as well. I bet they implement it in very the same way. If you have other recommendations or experiences, please let me know.

Now go forth and U2F all the things!

Holger

THINGS HAPPEN FOR A REASON

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.

Ray Dalio writes about his personal journey towards being one of the most influential and successful investors in history. On his way he made several mistakes, but he often recovered and eventually found his way to success. His work and life principles made all the difference for him. He evaluated himself in several psychological tests, as well as all his partners and employees. This way they could find out how this group of people was “wired” and how they could best work together. Ray encourages the reader to take some of these tests as well, to find out how you, the reader, thinks. What are your weaknesses, what is against your personality? Where do you excel at?

Once you identified your weaknesses you have at least three options for dealing with it :

• Ignore it
• Get better at it
• Delegate to people more capable than you

The first is the easiest and shouldn’t really be an option. The third might be a good solution for a few situations. If you know about this weakness, you are in a situation to find a solution because it’s not a blind spot anymore. So delegating this topic really might be the best option. The second option is the hardest, but might also offer the greatest reward. To get better at your weaknesses you have to constantly work on them.

Here’s one of my weaknesses that I found out about: I like to do high-level planning, create great strategies and execute on them. When it comes to the lower-level details of implementation I often get bored. I am a perfectionist in my work, but once things are at ~80% I tend to lose interest. This is a general trait of my character. I tested as an Architect.

I believe this sometimes shows in my work as well. I do not generally procrastinate, but I do not like to do repetitive tasks or more low-level stuff. I am thinking about writing all kinds of variations of tests, for example. I surely write the happy-path and the 80%/necessary tests, but I would rather take on the next task than bring test coverage up to 100% with all these tiny edge-case-tests… Also waiting on tests to complete… I’d rather continue reading my book! I believe I am not alone in that, but anyway.

Because I am feeling confident that “escaping from repetition or boredom” is a weakness of mine (just to give it a name 🙃), I devised a simple strategy for dealing with it. This email is rather getting long, so I will write about my strategy (and how well it worked) another time.

What about you? Did you take any personality tests? Do you know about your weaknesses (and strengths! These are also important to know)?

Holger

TEST DRIVEN DEVELOPMENT

Test-driven-development. There’s no other way to do this.

Always write tests first! Always have failing tests before writing the code! Write code in small iterations.

Write the next failing test once the first iteration passes the test. Repeat until finished.

That’s how you do it.

Or not.

You can write your feature, your code. And write a test afterwards. Like a regression test. Sometimes that’s what you do, when you use snapshot testing for React components.

Either way it’s your decision as a professional to make what way you want to develop and test. You get paid to make the right decision, but it is your decision to make. Not somebody else’s. Please don’t forget that. Don’t run around and blindly spread the gospels of our software dev gods. You get paid for thinking and without thinking we could have a machine write the code for us.

Holger

SOFTWARE DEVELOPMENT ON CONSTRUCTION SITES

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.

While I couldn’t do anything to improve his situation, I absolutely understood what he was going through. And after a couple of days I happened to be on my way to passing the construction site. I was doing some running and it was convenient to just pass along there. I thought, I should really check out this site. After all, they must’ve already finished a lot, if they’re always building and doing things. When I passed the site, it was empty. It was quiet. There was nothing going on. My run was in the morning, I passed the site at around 8:30am. Well so much for that! 😅

This made me think: I had heard a generalization from a trusted source and had assumed it was true. I had made further (innocent and unimportant) choices based on that generalization. Do we do that a lot? Do I do that a lot?

Turns out, probably more often than I thought.

Example: In my current project, I am building a BI dashboard for my client. My latest task was a new widget displaying numbers about some products in a nice chart. It was actually a different way, displaying slightly different numbers, for another widget that was already present. The new one took the same numbers and looked at them from a different angle. At least that’s what my client told me in the initial briefing. The name of the new widget and the sketches and wireframes that I based it on all told me the same thing: The widget’s source data is the same as for this other widget.

Only, it wasn’t… Once again I took a “simple fact”, trusted it and noticed later that the source of the fact was wrong.

In the end that wasn’t a big deal. It was easy and quick to correct and the client even noticed that he was the source of this. But! I could have noticed it sooner, if I had asked more questions. (More of the right, important questions. Which these are is a topic for another email, though…)

Do you have situations like this as well?

Holger

DID YOU JUST CLICK THE LINK?

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.

Change your opinions, keep to your principles; change your leaves, keep intact your roots. — Victor Hugo

I write lots of text in English. These are mostly texts like this, or documentation for software I’ve written or discussions on Pull Requests, stuff like that. But I also write German, in the texts with my wife, in emails to other Germans etc. When writing software code, I tend to use the U.S. keyboard layout. It just so happens to be easier to use for development with its placement of characters necessary for development. But I also need the umlauts when writing German words. So I switch a lot of times between the layouts. It’s fairly easy on Mac OS, I just press the shortcut Ctrl-Option-Space (you can set this in the System Settings). But since I switch between different apps a lot during the day it always incurs a small overhead for me to see if I have the right language selected and change it if necessary. Or it happens that I just begin typing, only to notice mid-sentence that it’s the wrong layout. So I automated that!

Whenever I switch apps now, the computer automatically switches to the (most of the time) correct layout. My IDE, editor, terminal and other dev things have the U.S. layout, most other apps have German. My browser (Firefox) is a standout as it depends on the tab that’s open which language I need. I tried to automate that as well, but it isn’t perfect yet—tab titles change all the time… If you’re wondering how I did that, I use Keyboard Maestro for that. It is a really “not so pretty” interface, but it works alright.

The other automations/shortcuts I created recently involve my keyboard launcher Alfred. But that’s a topic for another day.

Holger

GDPR, OR: HOW I STOPPED WORRYING AND LOVE MY USERS

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.

This marks the latest installment in a series of emails and events that date back to around 2009. Since then I received emails about hacks at companies that kept my data almost yearly. I am fed up with that. But there is little I can do myself. Gladly the EU has my back, well more or less…. The GDPR came into force on May 25th and now things will change? Depends on the people! Everywhere you could hear developers screaming and cursing about this regulation and the amounts of work they had to do to appropriately deal with it. While I do understand them (I had to do the same work on my business and websites and on my clients’s) my standpoint is a little different. I am an optimistic person who always sees the light and tries to find ways to optimize or at least improve situations. And the GDPR represents on of those. You see, you have to deal with these things required by the regulation anyway. You can’t escape them. So let’s take the opportunity and do the work necessary to fulfill the requirements, and then some. The regulation offers enough single points that you can take and make your systems more secure. It offers you ideas that you can take to your manager to get the clearance the implement them, that reduces the risk for your customers if you ever get hacked. And for many of these points you have to implement some simple version anyway. Why not go the extra mile and take care of the important stuff. Like, treating your customer’s data with the same confidentiality and importance as your own business data?

Okay enough rambling about that. Because I really like that topic I even gave a talk about it at the Isle of Ruby conference in April. You can find my slides here: https://www.slideshare.net/5minpause/gdpr-or-how-i-stopped-worrying-and-love-my-users

If you want to talk about that some more, please feel free to write me an email.

Holger