Kiril Mitov blog

How the software becomes unmaintainable? – a practical example

(Everyday Code – instead of keeping our knowledge in a README.md let’s share it with the internet)

An ugly, sometimes over neglected truth of the industry is that the software that we work on does not become unmaintainable and tedious and difficult to work with overnight. It becomes like this with every change we introduce. While each individual change might not be “that bad” when they pile up we no longer have a well decoupled, maintainable system. We end up with a mess, which we than re-write with a new framework, a new team, new concepts and architecture just trying to do better. But the problem most of the time is in the single change that we do today – is it making the software system better or worse?

This article is about a practical example of today and how we got to stop it.

To better or worse

When developing software incrementally we introduce changes. There are basically two options – the new changes would make the system better or they will make it worse.

Here is the change from today

--- a/file1.rb
+++ b/file1.rb
@@ -8,6 +8,7 @@ module IsBackend
 
     def embed
+      @full_video_src = @material.video_refs.where(usage_type: "full_video").first.try(:video).try(:source_url)
 
diff --git a/file2.rb b/file2.rb
index bce7cd1a0..43b3768ea 100644
--- a/file2.rb
+++ b/file2.rb
 
   before_action do
     @namespaces = [:author]
+    @full_video_src = @material.video_refs.where(usage_type: "full_video").first.try(:video).try(:source_url)
   end

diff --git a/file3.rb b/file3.rb
index 650456cb0..8c772288a 100644
--- a/file3.rb
+++ b/file3.rb
@@ -41,6 +41,8 @@ class MaterialsController < CommonController
     @client_import_path = "shared" if Rails.application.config.platform.id == "b3"
+    @preview_video_src = @material.video_refs.where(usage_type: "preview").first.try(:video).try(:source_url)
+    @full_video_src = @material.video_refs.where(usage_type: "full_video").first.try(:video).try(:source_url)
   end
 

The logic is not important. We basically get the video for a material. What’s important is the code is practically the same in all 3 places. 4 calls in three files and they are all the same.

In the past I was leading a class in Software Development. One thing I tried to teach each student was:

When you copy and paste you introduce a bug. That’s a fact of the industry.

The reason is that once you copy/paste you would have to support the same logic in more than one place and you would simply forget about the second place the next time you would like to change the logic. It might not be you, it might be colleagues working years from now on the same code, but they will forget to change both places. That’s the problem with redundancy.

How did we stop it?

Simple review. Just ask a second person to check your commit. This simple review process protects you from a large portion of the other bugs that are still left after you’ve cleared all the redundancies (of course).

Enjoy

The code in question is part of the logic delivering these instructions. See how the video is displayed. That’s what the feature was about. Enjoy.

Torvi – Ball shooting Lego machine