I want all involved in development to think about other users. Not about those who use your application to solve their problems. But those who extend your app, run it in production and integrate with other systems. About developers, operations, SREs and many others who make your business running. Those behind the curtains. I want you to think about the Developers Experience (DX). The problem Working with different businesses and in outsource companies I’ve spot following tendency: The main focus is on business requirements and UI features of built application. Because this is the first thing that real users will see. A client who ordered a new feature would like to see a pretty demo and understand that money invested is working. Such priority looks logical and right. But problems are hiding behind such thinking. always There are many other users behind the curtains. Almost nobody thinks about developer experience (except IT-focused products). Giving priority only to business features and UI is not enough for some solutions. Nowadays all businesses are digital. They integrate with many systems, chats, banks, you name it. There is always some development work happening and many of them don’t focus on DX. Which is bad. It is bad because engineers also should feel happy using your product. If they struggle, you as a business might have loss of trust or reputation. All users of your product are special. Yes, they all have different needs, but meet those needs. Culture DX is also about product vision. It is something that should be in your development team. It should become part of a culture. Understand what you create. Not from specifications but from the real users perspective. Frontend developers are more product-oriented than backend developers. They focus on users and their experience. Backend developers focus on algorithms and data structures. I know that there are backend developers who also think about their users. This article is not about them. The product team and people who have vision should teach others to see problems from the real users perspective. If you would like to bring innovations and raise the quality of the product — such thinking should become part of you. Bad DX examples What experience should engineers avoid trying to use your application? This is an opinionated short list of bad DX examples. If you have something to add — welcome to the comment section below. Bad API design Take a look at the following: GET /users GET /users?id={userID} NEW /users/create POST /users/update?id={userID} DROP /user/{userID} Do you feel pain looking at this? I do. It’s a mix of different things Semantics are not followed Not easy to understand straight away what is happening Not standard HTTP methods are in use (but this is fine according to ). RFC 2616 What is good is that it works. But it would be a lot better if it looked like this: GET /users GET /users/{userID} POST /users PUT /users/{userID} DELETE /user/{userID} Clean. Without looking at documentation such API already starts to give clues. Many frameworks ( , , , etc.) suggest following design of REST APIs by default. Actually, Roy Thomas Fielding was the first who . To start developing taste in API design take a look at or to get started. Ruby on Rails Laravel Play proposed REST this resource this article Another thing that I would like to mention is deep nested objects in API responses. Objects are trees and sometimes those trees grow like real trees. Very tall and dense. It is not good when your response object looks like this: { : , : , : [ { : , : , : [ { ... } ] } ] } "id" "001" "value" "some value" "child" "id" "002" "value" "another value" "child" To get needed values you need to traverse a graph. Algorithmic complexity to parse a graph is ( ). And it’s a lot. There might be too many nodes to traverse. It would be better to flatten such object. O(V+E) DFS [ { : , : }, { : , : , }, { : , : , } ] "id" "001" "value" "some value" "id" "001:002" "value" "another value" "id" "001:002:xxx" "value" "and another value" Much better. And this might be a final variant if the return object is small. Parsing the following structure will take (because of one loop). Nice. And reading such structure is easier. Is it possible to lower search to ? O(n) O(1) { : { : , : }, : { : , : , }, : { : , : , } } "001" "id" "001" "value" "some value" "001:002" "id" "001:002" "value" "another value" "001:002:xxx" "id" "001:002:xxx" "value" "and another value" Now it is . You can specify a key and extract value without iterating an object. Some may recall Redux by looking at the last example. O(1) State Shape Normalization TIP: Use the following approach to store objects under keys in cache. Solutions provided here are not silver bullets. Key takeaway: Keep your objects as flat as possible. Take a look at your APIs. Can somebody’s life be simplified? Configuration properties chaos Sometimes configuration properties are treated not seriously. Take a look at this snippet: base.url=http://localhost:8080 = jobs.disabled=true extract.values.and.save.period.hours=5 send.email.each.12.hours=true port 1313 Naming is strange and hard to read Hard to follow logic (because there is no logic) Time unit is big. It might be that there are properties set in other time units than hours It’s hard to figure out the meaning of some properties by their names etc. Treat configuration properties as first-class citizens. Developers and Ops interact with your application using properties. If it is not clear how to use them — mistakes may arise. Additionally it is a sign about the bad quality of your product. How to fix this? server.address=127.0.0.1 server.port=80 jobs.extract_reports.enabled=false jobs.extract_reports.interval=18000 jobs.extract_reports.destination=/tmp/reports jobs.extract_reports.email_notifications=false # Network address (server.address) to which the server should bind # and listen port for incoming HTTP requests (server.port). # Default: # Job to extract and save reports to storage. # If enabled (jobs.extract_reports.enabled) job will # run every 5 hours (jobs.extract_reports.interval in seconds) and save # reports to defined destination (jobs.extract_reports.destination). # # Enable email notifications # (jobs.extract_reports.email_notifications) to send summary # of jobs done during the day. # Default: Comments added — more context given Sensible defaults are setAll properties are logically grouped Application with set defaults will be able to start without extra configuration For inspiration I would recommend to take a look at: redis.conf postgresql.conf Logs with no meaning and action Logs are the main interface of your app for the Ops team. If logs lack context it might lead to long investigations of a problem. [ : : ] ERROR Exception happened com : Base Exception at com (HomeController : ) ~[bin/:na] at sun (Native Method) ~[na: . _45] ... at org (DispatcherServlet : ) ~[spring-webmvc- . : . .RELEASE] at org (FrameworkServlet : ) [spring-webmvc- . : . .RELEASE] at org (FrameworkServlet : ) [spring-webmvc- . : . .RELEASE] at javax (HttpServlet : ) [tomcat-embed-core- . : . ] ... 12 40 45 .ekiras .exception .BaseException .ekiras .controller .HomeController .ex1 .java 21 .reflect .NativeMethodAccessorImpl .invoke0 1.8 0 .springframework .web .servlet .DispatcherServlet .doService .java 893 4.2 4 .RELEASE .jar 4.2 4 .springframework .web .servlet .FrameworkServlet .processRequest .java 969 4.2 4 .RELEASE .jar 4.2 4 .springframework .web .servlet .FrameworkServlet .doGet .java 860 4.2 4 .RELEASE .jar 4.2 4 .servlet .http .HttpServlet .service .java 622 8.0 30 .jar 8.0 30 Such a log only states that something bad happened. For those who don’t have access to the code of your app this is almost zero information. Stacktrace will not give information on how to solve the issue. 12:40:45] the database (db.internal/app) failed. Check datasource property application configuration ERROR Connection to in The message above is clearer because it states directly: What is the problem — DB connection failed How this error can be fixed — check property datasource Usually, machines collect logs first and after humans read them. If this is the case, write log in JSON or structured text formats: = =error = =500 = time "2020-06-14T01:27:38-04:00" level msg "Connection to the database (db.internal/app) failed. Check datasource property in application configuration" status_code path "/about" With the example above, logs can have more context like response status code and path that failed. The following format is readable by machines and by humans. Rule of thumb: One event equals one log line. No comments in code When you want to use some method from the library and it doesn’t have a description — it’s a problem. { } List<User> public users (Bool limit, String group, String sort) // ... Guess games, anyone? The assumption is that it will return the list of users. But what is , and ? What are their values? What can be set there? limit group sort Without comments we need to read code to understand what is happening there. After reading open Pull Request with the following comment: { } /** * Return list of users. * * limit specifies to get users with limited access (default: true) * group user group to lookup (default: "regular") * sort how to sort users (default: "asc"; possible values: "asc", "desc") * list of users */ @param @param @param @return List<User> public users (Boolean limit, String group, String sort) // ... Congratulations! You’ve got angry developers who spent a lot of time understanding code that they should not even know. is playing this game by . And another player is , who go with approach. Go making comments mandatory Rust documentation comments as tests Self-documenting code is a myth. Document your code. Users and the future self will be very grateful for such effort. Unpredictable responses For example, you want to get a list of prices set for some item in the shop during the specified day. API response might look following: { : , : , : [ , , ] } "item" "78956745" "day" "2020-06-14" "prices" "8,72" "9,01" "8,02" What if there were no price changes during the day? Item ID and day are valid. The only thing missing is the list of prices. Consider the following options: 1) Prices are returned as an empty list: { : , : , : [] } "item" "78956745" "day" "2020-06-14" "prices" 2) Prices are not returned: { : , : , } "item" "78956745" "day" "2020-06-14" 3) Prices are set to null: { : , : , : } "item" "78956745" "day" "2020-06-14" "prices" null Two last options are not predictable. Option 2 modifies response by removing object from the response. Not good. Option 3 makes it worse. You saw that in response there is a list and now you observe different type. prices The best approach is to go with Option 1. You know that is a list. In future, you also expect that there will be a list. If there is no information, then return an empty list. Less confusion and meet expectations. prices Only once executed configuration properties You can give an option to the user to configure your service via configuration files or APIs. In some scenarios, this does make sense. But sometimes there is a case when configuration in a file is used only once to bootstrap an app. And then only the API is in use. Don’t do that. If you provide both options — both of them should work the same way. Do change in file — changes apply. Do changes via API — changes apply. Configuration operations that users do should be . idempotent It doesn’t matter how you set configuration — it should always work the same way. How to level-up DX It’s all about thinking. And thinking is something not easy to change. I would suggest to start with . It is a set of good practices to apply. It’s more oriented towards backend applications, but ideas can apply to other areas as well. Take a look at for inspiration. This is one of the companies that is known for great DX. Another company that I like and it inspires is . Also suggest to read fresh and nice article from Chris Coyer . Are you building CLI? Get inspiration from Carolyn Van Slyck talk on . The Twelve-Factor methodology Stripe Digital Ocean about meaning of DX for different people how to design Command-Line tools that people love And ask yourself questions: Who are end users / stakeholders? Is it another team? Other developers who perform integrations? How will this library be used? Can this be simplified? Is this readable and understandable? Does it look simple? Will my colleagues understand this? And ask for feedback to become even better. Hope you enjoyed it. Happy coding and nice mood!
![The Eternal Quest for an Interview Process That Doesn't Suck [An Analysis]](https://hackernoon.imgix.net/images/cu1id3kho.jpg?auto=format&fit=max&w=3840)
