3 practical steps to self-documenting code

Applications can get out-of-order and quickly. Unfortunately, some get to a point where they are that complicated, they’re largely un-documentable and inexplainable. Tackling this type of project takes a specific mindset.

When a code base reaches a certain level of complexity it simply cannot be explained.

So – that’s where self documenting code comes in – your code needs to be broken up and made simple in order to be understood.

Self documenting code means you can …

  • Onboard staff faster
  • Scale your team
  • Reduce developer headaches
  • Increase re-use of your code base
  • Have more cross-functionality within your teams
  • etc.

But … this is one of those topics spoken about a lot but commonly misunderstood and not put into simple and actionable steps, and that’s what I hope to do today …

3 steps to self-documenting code

  • Put things in boxes – Treat your code like you would your kitchen. Start putting things in drawers and containers that are similar so that when someone visits your code they can easily know where things are. When you visit someone elses kitchen you know where the knives are likely to be, right? Your code is the same! A box could be a folder, the name of your files or it could even be a new repository with its own documentation if your code is big.
  • Take action now – Logically separating all your code is a bit of an art and something that should be started TODAY, try not to get too caught up on the perfect solution as this will paralyse you into trying to predict the future (tip: You can’t predict the future, don’t bother!). Instead slowly go through the code and let the architecture emerge, and instead just invest continually and in small amounts.
  • Beware the word AND – When you ask someone what does a function do and they respond with “It does this AND it does this” – this should be ringing alarm bells for you … a function becomes unpredictable when it starts trying to do multiple things, this is the exact same when it comes to your application, make sure that each folder, each file, each function, each repo can be clearly explained without you saying “Oh it does this AND this AND this”.

I hope that gives you some ideas around what you can do to increase the reusabiliy of your code by putting it into boxes and thinking about keeping the concerns separate.

Question: What has helped you to achieve truly self documenting code? 

Lou is a Front End Software Developer who currently lives and works in London. A voracious reader with an insatiable inquisition.

Like this post?

Sign up for my blog updates and never miss a post. I’ll send you a FREE eBook as a thank-you.

* indicates required