Code Age
========

Code Age is a much underused driver of software design. In this guide
we'll cover how you interact with the analysis results and how you use
the presented information to guide your architectural decisions.

Drive to Stabilize
------------------

Code evolve at different rates. As you've learned in the Hotspots
Guide (see :doc:`/guides/technical/hotspots`), some parts of your codebase tend to change
much more frequently than others. The *Code Age Analysis* gives you
another powerful evolutionary view of your system. It's a view that
helps you evolve your codebase in a direction where the system gets
easier to maintain and more stable.

The age of code is a factor that should (but rarely do) drive the
evolution of a software architecture. In general, you want to stabilize
as much code as possible. A failure to stabilize means that you need to
maintain a working knowledge of those parts of the code for the
life-time of the system.

How do we measure Code Age?
---------------------------

CodeScene measures code age per source code file (or any
content, actually). We define the age of code as “the time of the last
change to the file”. Note that this means *any* change. It doesn't
matter if you rename a variable, add a single line comment or re-write
the whole module. All those changes are, in the context of Code Age,
considered equal.

This definition is fairly rough and in the future we're likely to take
the amount of change to a file into account when calculating age. But
for now, age is that time since the last change. And the resolution is
months.

Inspect your Code Age Distribution
----------------------------------

The age distribution graph shows how much of your codebase that you have
managed to stabilize.

.. figure:: CodeAgeDistroSample.png
   :alt: An example of code age distribution
   :name: code-age-distro

   An example of code age distribution.

The example graph in :numref:`code-age-distro` shows a codebase under heavy development. As you see,
20% of the source code files have been modified the past month. Here's
how you use this information:

-  See how much of the code you manage to stabilize.
-  Identify sub-systems that have become commodities.

Let's discuss these two points. First of all, you want to stabilize as
much code as possible. Stable code means that its quality is known. It
also limits the size of the codebase where a developer has to maintain
an active mental model of the code. New code (0-2 months old) is of
course where the current development happens and you expect some
activity here; a system that doesn't change is a system that no one
uses. What you want to look out for is everything in between. That is,
the code that's neither particularly old nor do we need to work with it
on a monthly basis.

The reason we'd like to avoid having code that is neither old nor new
has to do with human forgetting. Such code is old enough that the
original programmers are unlikely to remember the details. If we need to
dig into code that we no longer remember well, we pay a high price. So
please watch out for a codebase where you have a flat distribution.

The second use case for Code Age Distribution is to identify
commodities. A commodity is code that's been stable for a long time.
You see an example from the development of the Clojure programming
language in :numref:`code-age-clojure`.

.. figure:: CodeAgeSampleClojure.png
   :alt: Code age distribution in Clojure
   :name: code-age-clojure

   Code age distribution in Clojure.

This is a good starting point; If you have a lot of code, as in the
distribution in :numref:`code-age-clojure`, that you haven't modified in years, there's an
opportunity to drive your software architecture in a leaner direction.


Possible sources of Bias in the Age Distribution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As noted above, code age is measured since the time of any change to a
file. That means, if you re-organize your codebase by moving source code
files to different folders, your code will appear much younger than it
actually is.
