Full disclosure, you do have to lift a finger but not as many times as you think.
Do you think your code is half way between readable by humans and parsable by machines? Good I thought you would say that. Do you think you should be writing documentation for your code?
I disagree, you might feel guilty but you actually don't need to lift a finger to 'write' documentation initially, here's how:
1️⃣ Unit Tests
My post: What is a unit and how do I test it?!
As I didn't really specify the method of generating documentation, I'm defining it as unintentional act of doing something which yields documentation, and nothing makes better docs than a good suite of unit tests. By testing as many cases as possible you are defining the usage of a function, what it likes and doesn't like and how you can use it. 🐶 Good function, who's a good boy, he's a good boy.
2️⃣ xstate
Sometimes the underlying principles of your acutecure can be enough to generate powerful yet high level visualisations, take xstate for example, affiliated but not limited to React (I'm not a react developer), using this state machine as the basis of your application, the simple act of just pasting your state machines into thier visualization tool can give you amazing charts, yes you heard me, charts that model your state code, super!
3️⃣ JsDoc or similar
Turning your useless comments into a formal syntax is also enough to generate yourself some nice documentation pages, the more you put in the more you get out, not only that but vscode fully supports this style of comment and with markdown as well.
4️⃣ Typescript
If you know you know, Typescript is a form of documentation as declaring types in your code is information, similar to unit tests, explicit types tell other developers and you 3 months from now, how to use your code.
Top comments (0)