Home

Write documentation

TLDR; You need documentation in your code

Code is meant for humans to read and incidentally for machines to execute. I've explained why in a previous blog post (basically, you need to make it clear what you want your system to do).

Can you express what your system needs to do with code alone?

No because computer languages have constraints that a human language does not have. These constraints limit how you can express your ideas.

The reason for these constraints are valid. They exist because computer languages need to:

  • get compiled into machine instructions
  • need to make the programs you write in them relatively safe
  • ...

These are constraints a human language does not have. It can focus on being as understandable and expressive for humans as possible.

So how should we think about code vs documentation?

In a nutshell

  • Documentation = Say what you want to accomplish (the "why?")
  • Code = accomplish it (the "how?")

Or

  • Documentation = declarative
  • Code = imperative

But isn't it sometimes overkill to write documentation?

Yes absolutely. Sometimes when you're lucky.

You can aim for code that does not need documentation. It's a goal that will help your write excellent code. But don't fool yourself that your code is so excellent that it does not need documentation. that would be perfect code. perfection does not exist.

But don't you risk documentation getting out of sync with the code?

Yep this is a risk with our current tools. Some day I am going to build a tool that will mitigate this risk (this will be the topic of a next blog post). Currently, the best we have is to write documentation in a way that mitigates this risk. there is a lot written about how to do this. One book I highly recommend on this topic is this one

What about domain specific languages (DSL)?

Ideally every computer program should be a DSL + instructions in that DSL. That's why I'm a big believer in language-oriented programming. However I don't have any practical experience with that so unclear if I can be as fast doing it this way.