Documenting Code

2023-11-06 00:00

The other day I was dealing with a lot of changes to something all TypeScript, Java and C# developers most likely are familiar with: documentation in comments wrapped in various xml and other formatting.

We all do this to provide helpful information to other developers (or ourself in 2 weeks), either because it finds their way to some documentation generated from it like a web page etc or in your IDE of choice.

It is really fucking dumb.

Then I had to write some Python code and was reminded that they have built in support for doc strings. Not perfect but an improvement. And then I started to think: we are so few languages like this?

I vaguely remembered Clojure had something like this. And started to look into that. Their solution is interesting, and powerful but I wish it was a bit more integrated into the language for more symbols like parameters etc.

All of this brought me back to this:

  • When you write some function, class etc you want to add some information to those who will use it
  • It would be nice if languages had built in support for documenting any symbol, where it took care of all the details the language already know like types etc.
  • Where you could make builds etc fail if not provided
  • No comments
  • No weird formatting etc

Made with ❤️ in Bergen, Norway by Eivind Hjertnes