Skip to main content

How to significantly improve your code base with ADRs, RFCs and TODO comments

· 6 min read
Ivan Barlog
Ivan Barlog
AWS Solutions Architect @ BeeSolve

In this article we'll go over 3 simple things you can start doing today which have potential to significantly improve your code base.

1. ADR - Architecture Decision Record​

Architecture decision records should serve as view into architect's mind for the future architects. You can read on the decisions which were made before you and understand how someone who decided something before you thought about the problem.

This of course only works if all the ADRs are read by whole team on regular basis and are kept up to date.

An architect in this case can be whoever makes decision about code, infrastructure, used tools, methodology or anything else you might want to argue about in the future.

From my experience it is good to have both ADRs and RFCs (see next section) close to your codebase. I usually put my ADRs and RFCs to .md files inside docs/ folder right in my repository. This way the documentation is easy to search and it is also versioned.

Good practice is to number your ADRs. For instance I would create structure like this:

docs/
├─ adr/
│  ├─ archive/
│  │  ├─ rfc001 upgrade yup to the latest version.md
│  ├─ adr002 using valibot instead of yup.md
│  ├─ rfc003 modularize codebase by tool.md
│  ├─ adr004 using ECS instead of Kubernetes.md

As you can see the docs/ folder contains another folder named adr/ - this is simply so you can have other non ADR/RFC parts of documentation within docs/ folder. I usually also create archive/ folder where I put ADR/RFC documents which are obsolete. In the above example you can see that RFC001 has been archived because we moved from yup to valibot hence updating yup to latest version does not make sense anymore.

The structure used above is not set in stone eg. you can adapt ADRs/RFCs however you like, the important part is to number them so you can easily reference them and to make sure the content of the documents makes sense in your particular situation.

In order to leverage full advantages of ADRs and RFCs you should review them regularly.

2. RFC - Request For Comment​

Requests for comment should serve as a step before something became ADR. Eg. this is the proposal for any kind of architectural change. This should be read by all members of team and commented on demand as part of the document itself or as part of code review/pull request.

Once the discussion evolves to some decision or someone decides upon some actions the RFC should be renamed to ADR - the number can stay the same or the RFC might be archived and new ADR with new number can be created - entirely up to you and your team.

Inside RFC you should address your concerns and/or write about your ideas. Eg. RFC might contain "nice to haves" which you currently don't have time for.

If you are following any kind of agile software development like SCRUM and you have planning meetings reviewing RFCs and ADRs should be part of your agenda. This way the whole team understands what ADRs and RFCs are for and they can asynchronously discuss improvements and decisions about the codebase.

3. Tracking of TODO comments​

Another great way of improving your code base is by tracking technical debt. Technical debt is very hard to estimate and even harder to manage - especially when you need to find the balance between going fast and not making too much of a mess. In my experience TODO comments are the great source of truth regarding the technical debt of any codebase.

Everyone knows what TODO comment is. Whenever you don't have enough time and you want to move forward it is very simple to just add another TODO comment to your code base and let you or someone else to deal with it later.

The problems of TODO comments has already been described elsewhere. You probably know that at some point you start ignoring TODO comments altogether. Some of them become stale and for some of them you will never remember what was the original intent.

My advice is to track TODO comments in your favourite issue tracker for example Github issues. It has several advantages:

  1. most of TODO comments introduces technical debt - when you track them in issue tracker you can track your technical debt easier
  2. you can plan for implementing TODO comments when they are tracked along other issues
  3. by creating routine out of this you get rid of some TODO comments straight ahead
  4. when you create issues for your TODO comments you create documentation for others
  5. your future you and your colleagues will love you for this

Since you are adding TODO comments because you don't want to be slowed down whilst presumably in the state of flow it does not make sense to jump to issue tracker whenever you add TODO comment. Also there are temporary TODO comments which are being deleted few seconds/minutes after they are created.

I recommend to track all TODO comments right before you commit your changes. Simply do the git diff, search for // todo: (or whatever way you are adding your TODO comments) and go add one by one to your issue tracker.

When adding TODO comment to the issue tracker try to describe at length why you added the TODO comment, what was your thinking (make snapshot of your current brain so anyone else can pick it up later) and also explain in detail what needs to be done and how would you approach it if you had time. After that simply replace your TODO comment in the codebase with link pointing to the issue you've just created eg. // todo: https://issue-tracker/issue/123. If you want you can also leave some short concise description of the issue in the comment but anything else should go to issue tracker.

When you build this routine two things happens automatically:

  1. for small TODO comments you realize it might be easier to implement them straight ahead avoiding burden of tracking them and creating description of simple things
  2. by enforcing yourself to describe the issue you might come up with solutions easier because describing the problem within issue tracker is same as using rubber duck

Conclusion​

All of these 3 methods are very smiple and powerful. I strongly recommend you to go and try them. Start small, pick up your first TODO comment or ADR or RFC.

Unfortunatelly these things always works only when people are doing them on regular basis. It won't help you much if just one team member starts doing this so I suggest you to discuss these approaches on your next planning meeting or in your next retrospective 🙂

I hope it will help you as much as it helped me in the past.