Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship

Features don’t live in one place. They live across different files, folders, systems. Building on top of a system requires you to know what goals are being pursued, what problems are being considered, how they’re approached, implemented, tested… You are always reading. A better reading experience = a better developer experience.

Easier to understand means:

Faster Development

Faster Onboarding

Happier Developers

We have been using folders and files as our primary organizational tools since their invention over 60 years ago. We can do better.

Unlike regular documentation writing tools, Cartography code is designed to be the way you write code, making it both easier to read and to write. Documentation tools fall into two categories: manually written, and autogenerated.

The first type of documentation (manually written) is often a separate step in the development process done after writing code. As such, it is often forgotten, making your documentation out of sync with your source code. If your documentation can’t be trusted, then it won’t be used.

Autogenerated documentation doesn’t suffer from the “out of sync” problems of manual documentation and works great for certain types of tasks. It’s main drawback is that it is limited to a very basic scope: data type information, class lists, API usage, etc. This is rarely enough for you to understand how things work.

Cartography, through Code Stories, and Entity Libraries, encourages you to describe your problems, goals, and approaches as you write your code. With this, you never lose context of how features were developed, and how they work. All the code related to any step exists in its own little compartment. As such finding code, is as simple as finding the feature you are looking to develop.

Cartography provides many tools for interacting with your codebase.

Often times, we will create systems and patterns for interacting with them. The most basic example of this where you create a function. Later on, you want to call this function, which involves importing the function, and calling the function. With code symbols, we can abstract out how that happens. We can create a “import code symbol”, anda “call code symbol”. Now when we decide to change the order of the parameters, or the naming of the function, all imports and function calls can be updated.

A more complicated example would be a symbol that defines a child class of an abstract base class. Having such a class would remove all the boilerplate required for the definition, while simultaneously exposing the API, and patterns for dealing with certain use cases. These types of code symbols allows others, such as more junior devs, to use your abstractions as intended.

Code Actions are an API for interacting with your Codebase. Like static code generators, you can define actions like “Create new Data Model” which will create the files, and boilerplate required to create your code. Another common action would be are things like: “Add new page view” which would create a boilerplate page template and add the route to the router. If used in conjunction with Code Symbols, unlike regular static code generators whose code must be managed manually afterwards, you can refactor the generated code after the action has been instantiated.