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