Dev Blog #7 - Technical Debt, you don't want to wait for the bailiffs to call.

People who have seen either my or Faustie's forum posts, or were around for the community meeting have heard us talk about technical debt, but we haven't really explained what it is or what it means.

What does Wikipedia say?

Technical debt (also known as design debt^[1] or code debt) is a concept in software development that reflects the implied cost of additional rework caused by choosing an easy (limited) solution now instead of using a better approach that would take longer.^[2]

Wikipedia, licensed under CC Attribution Share Alike.

That doesn't really help much, does it?

In simple terms.

Technical Debt is just like real debt. You borrow from the future, to the benefit of now. Whether that be building systems which "just work", without considering how that can be expanded in the future, or not documenting complex systems. It works now, but takes more time and effort to fix later.

Is this a bad thing?

In the short term? No. We all write code first, get it working, then make changes, optimise, write documentation afterwards. So long as it stays limited, and gets fixed quickly, before the system goes live? That's just how development works.

So, how does this effect Limelight?

Well, it takes a few forms, affecting different developers differently.

Documentation

This is a big, big issue, affecting both gamemode and web developers. People have been annoyed by my documentation updates, but they're needed.

Documentation, to keep it simple, is written words, used to pass information between developers. Most documentation is written as a "func-doc", or function document. It's a block of text explaining the function, what it does, its arguments and returns.  

This is an example from L2 Plates. Not the best example, but it gives a broad overview of what the function does. It draws a license plate on a vehicle. Each argument is explained. Each argument type is noted. At a glance, you know how to use the function.

But, there's another layer, the function and its arguments are self-documenting. The function name is readable and describes what it does (it draws a plate). You can guess what each argument is. The entity being drawn on, the plate data, the license plate text, the plate title, the material and colour being used, and a set of trace data. It's easy to understand and quick to read.

Let's find a bad example.

Here, the name of the function (player has free laptop) doesn't match what the comment says it does (enforcing a player's laptop REP restriction), it takes me longer, as I have to check the code to see which is right.

This sort of thing makes it slower to develop, and easier to get things wrong.

Testing

Not so much a problem in CityRP, but more with web development. Anyone who's paid attention to my discord's open source library channel has noted a lot of commits relating to testing. This is automated unit testing, to make sure the libraries works as intended, and that changes I make don't break stuff.

For example in the PHP version of InterDB, there's currently 5 test sets, running 21 tests with 31 checks, and that only covers 54% of the code.

Compare that to Limelight services, where, as of writing, none of our code is tested automatically. This means that changes can accidently break stuff, and if nobody notices, it might get pushed live.

Yikes.

Old Code

While old code isn't bad in itself, it's often a product of the time it was written. Code can be slower, use features that have been / are being removed, or just extremely unclean. Again, as I keep saying, it makes development today slower, in exchange for getting it working in the past.

What are we doing?

Quite a bit. New Style Guides, requirements to document code, testing requirements. Training developers to recognise poor practices, and rectify them.