Thoughts about software development

Simplest solutions are usually the best solutions. We as software developers work with hard problems and solve a lot of small problems every day. Solving a hard problem itself is a hard job. Though in my opinion it's not enough to solve a hard problem in any possible way but a hard problem should be solved with a simple solution. When a developer comes up with a simple solution to a hard problem then they can declare the problem solved. First a disclaimer. Coming up with a simple solution to a hard problems is itself a very hard problem and takes a lot of time, effort and practice. I've seen my share of "clever" solutions for hard problems and the problem with those is that usually the solution itself is so hard to understand that depending on the size of the problem it may take a developer from hours to days or even weeks to understand how that "clever" solution works. It's a rare occasion when a developer has come up with a simple solution to a hard pr...

Seven ways to write the same code snippet  Here are eight ways to write the exactly same code. Some are easier to read than others and all are a variation of a code I've seen in a real code base. My personal favorite is #7, what's yours?  #1 One liner DAO.filter { it.name == "foo" }.map { it.company }.toSet() #2 two lines, three operations DAO.filter { it.name == "foo" }   .map { it.company }.toSet() #3 Evaluation on it's own line DAO.filter {   it.name == "foo" }.map { it.company }.toSet() #4 Each operation and evaluation on their own lines DAO.filter {   it.name == "foo" }.map { it.company } .toSet() #5 All function calls and evaluation on their own lines DAO   .filter {     it.name == "foo"   }.map { it.company }   .toSet() #6 Everything on it's own line DAO   .filter {     it.name == "foo"   }   .map { it.company }   .toSet() #7 All function calls on their own lines DAO   .filter {  i...

Readability, understandability, two key incredients of great code. Easier said than done, right? What one person finds easy to read and understand another one finds incomprehensible. This is especially true when programmers have different levels of understanding on various subjects e.g. object oriented vs. functional or Node.js vs. Java. Even though there are obvious differences between paradigms and programming ecosystems there are some common conventions and ways to lower the barrier. Different approaches It's natural that in programming things happen sequentally e.g. you can have a list of objects and you need to do various things to the list like filter some values out and count a sum of the remaining objects based on some property. With the given list const stories = [   {name: "authentication", points: 43},   {name: "profile page", points: 11},   {name: "shopping cart", points: 24},   {name: "shopping history", points: 15},   {name: ...

There are two hard things in programming and naming is one them. If you don't believe me ask Martin Fowler https://www.martinfowler.com/bliki/TwoHardThings.html . In this post I'll be covering some general conventions for naming things to improve readability and understandabilty of the code. There are lots of things that need a name in programming. Starting from higher abstractions to lower we need to name a project, API or library, we probably need to name the source code repository, when we get to the code we need to name our modules or packages, we give names to classes, objects, interfaces and in those we name our functions or methods and within those we name our variables. Overall a lot of things to name. TLDR; Basic rule There's a single basic convention to follow to achiveve better, more descriptive naming of things. Give it a meaningful name i.e. don't use shorthands like gen or single letter variables like a, x, z instead tell what it represents, what it does...

Currently the most popular version control system is git and I'll be writing this based on git and it's functionalities and capabilities. Git is often seen as a way to enable distributed programming i.e. multiple programmers can work on the same code repository quite easily without disturbing each others work (much). In addition to that just like other VCS's it's also a log of work but to my experience that part is often unfortunately neglected. What I will be focusing this time is the log part because I think it deserves more attention. Why to create a meaningful log? The git log should consist from small meaningful changesets where each commit addresses a single problem. By dividing the log to small commits it enables resilient way of working. Being resilient enables simple and fast procedures to rollbacks, reviews, tags, branching etc. Lets say that a developer is implementing a REST API. The API needs a web layer that receives the HTTP requests, it probably has some...

Acceptance test are a great tool to verify that the application or system works as expected from end to end. Sometimes these tests can be called as end-to-end tests but sometimes end-to-end tests have a different meaning. Another term to describe the same functionality is QA tests and a subset of acceptance tests is often referred as smoke tests. The idea The idea is to define a input and the expected output and once the system and all it's dependant services are running the whole system can be verified to work as expected. In a ideal world the acceptance tests would be implemented based on the acceptance criteria of the use case. The implementation Acceptance tests can and should be implemented in the code just like unit and integration tests are implemented. The acceptance tests don't neccessarily reside in the same code repository as the code but they can, depending on what's the need. When a system is API the acceptance tests could be e.g. predefined HTTP requests with ...

Integration test is something that tests a functionality that is dependant on a external system e.g. a database, HTTP API or message queue. Integration vs unit tests The line is thin in my opinion. The integration part can be faked or a embedded services can be used in place of the actual integration point and with these solutions the interaction with the external system is bounded in the test context and the tests can be executed in isolation so they are very much like unit tests. The only difference with this type of integration test and unit test is that the startup time of the embedded or faked system usually takes some seconds and that adds total execution time of the tests. Even though the total test exection time is longer all the tests need to pass and all the cases need to be covered whether there's external systems involved or not so the importance is equal between the test types. This is why I wouldn't separate unit and integration tests from each other within the co...

Unit tests are the developers number one safety net. Let that sink in. This is the number one reason for writing unit tests. Unit tests are written by developers for developers to ensure that the code works as expected and handles happy and sad paths correctly. With enough unit test coverage the tests enable a safe environment for refactoring and rewriting code. Unit test scope Unit test should test a single thing, a method or function call and it should test only one use case within. In other words a unit test should test a function with a single input. This is a important guideline to understand. When a unit test tests a function with single input it makes the test isolated, repeatable and predictable. Example of good tests: @Test fun findsAddress() {   val address = findAddress("Stevens street 35", "Southport", "Australia")   assertThat(address).isNotNull() } @Test fun doesNotFindAddress() {   val address = findAddress("Stevens street 697", ...

Immutability is a special thing that in my mind deserves a short explanation and praise. If you're familiar with functional programming you surely recognice the concept of immutability because it's a key ingredient of the paradigm. In the world of object oriented programming it's not as used and as easy to use approach but there are ways to incorporate immutability to parts of the code and I strongly suggest you to do so. Quick intro to immutablity The basic idea of immutability is unchangeable data.  Lets take a example. We have a need to modify a object's property but because the object is immutable we can't just change value but instead we make a copy of the object and while making the copy we provide the new value for the copy. In code it looks something like this. val pencil = Product(name = "Pencil", category = "Office supply") val blackMarker = pencil.copy(name = "Black marker") The same idea can be applied in functions and metho...

Code works around contracts and contracts should be carefully thought and crafted. What are contracts A High abstraction level of contracts for code are API's. They define a interface that is basically a contract that the producer and consumer of the API agree to use to communicate with each other. Two common forms of API's are libraries that are used in code and external API's  that are used via HTTP, RPC etc. When thinking in a bit deeper contracts consist firstly of functions, methods or external endpoints and secondly of data, more precisely on data models and data types within the models.   Defining contracts Contracts should always be defined with careful thought. I've come accross few times to someone saying that "this is for intenal use only so it doesn't need to defined and/or documented as thoughtfully as a public API would be" but I disagree with that. The same care should be be given to internal and external contracts because the contracts are ...

What makes a good function or method? I don't think it's a single thing but a combination of things where each is significant. If one the things is flawed it affects to all others and the whole function is flawed. So what are those "things"? Have a meaningful name Function should have a name that describes it's purpose or functionality. When a function has a meaningful name it's easy to read and understand what's it's purpose. Let's take a example. If function's purpose is to find a customer by it's id a good name could be findCustomerById(id: String) or it could just as well be just  findCustomer(id: String) because the function signature implies that the customer is found by it's id the word find also implies that the customer might be found or it might not be found. If the function's name would be changed to getCustomer(id: String) it's meaning changes because now it implies that there's no fallback, the customer is e...

I've been writing a series of blog posts trying to summarize what are the key incredients of good code. The working title for the series was called "my view of clean code" but clean code is already a existing term (and a book, read it if you haven't). My view is mostly same, a bit different and with a idea that these are not rules or laws but conventions, ideas and practices that can be applied in many situations but this is not a silver bullet. I'll be publishing ten posts in addition to this one on various subjects that relate to code, code bases, interactions in code or interactions between systems and how to build all this with the aspire to make everything simple so that the code is as easy to test, reason and as understandable as possible. Each post will be a short and simple description of the subject with possibly some example code. A new post will be published every other week. In the first part I'll be writing about functions and methods and that wil...