- The learning point that @yawaramin already mentioned.
- Documentation is the only tool we have to convey important information to the user of our interfaces. In many languages, the concepts of ‘Documentation’ and ‘Commenting’ are conflated, but they are different:
- Comments are something you write in your code to help you and future maintainers understand why you made a certain implementation choice (like picking a less aesthetically pleasing solution because the performance difference mattered here, or make a note that yes, this line is required because otherwise a race-condition would happen in situation X, etc.). Side note: Comments should not tell you what happens (because, hopefully, the code itself already does this).
- Documentation, on the other hand, is for people using your code, who need to know the rules your code expects of them. This is even more important in a weakly-typed environment than a strongly typed one, because there are less ways to enforce rules on the end user (to ‘make invalid states impossible’) so the only tool we still have is communication between humans.
The nice thing about making documentation first-class (rather than having documentation ‘tacked on’), is that it is a lot easier for people to find and use it! I find myself using iex’s h helper very often, because it is so much quicker than browsing on the internet to look for the documentation of packages/modules that I already have installed on my local system.
