Robots writing docs
Automating code documentation tasks @ Fiverr
Following a commenting guideline
The popularisation of documentation automation tools like javadoc and jsdoc has re-introduced the standard of commenting guidelines. Keeping a uniform comment style is beneficial for the same reasons code style guides are; it contributes to conformity of code, ease of peer reviews and collaboration and minimises research efforts for unfamiliar parts of the code-base.
Readable code, Well commented code, Documentation.
When we select libraries to use in our own program, we require an accessible documentation. We check for one before (if at all) reviewing their code base. We consider it a necessity of external solutions. As our company grows, we begin to understand this feature is as important for internal projects and packages. Our developers will start using the tools we build without diving into the details. Top level documentation can accelerate implementation.
Starting to document your code according to a guideline seems tedious on it’s own, practices of readable code suggest it is redundant. I’m doubtful most developers will sustain such a paradigm, but if it was accompanied by instant gratification, the benefits are more visible.
Inline documentation
This is where inline documentation and automation tools come in.
Since comments accompany definitions in the source code, structured comments become part of the peer review process and their formatting becomes part of our organisation’s code styling guide. Peers start to demand readable, well formatted documentation to perform their code review.
Keeping documentation concise and readable becomes a necessity. Otherwise, it will take over entire files. The rule becomes: “If you can’t explain your method in a sentence, chances are you need to break it down.”
Variables and constants are also being documented. This means we are able to use a bit less descriptive variable names when they get too long.
The fulfillment: accessible documents
At Fiverr, we’ve started composing automated tasks for creating documentation out of structured comments.
On one of our open source repositories, for example, the CI (continuous integration) pipeline job carries the credentials for a dedicated user, Alvy. This user was assigned writing privileges on certain unprotected branches of the repository.
Alvy’s work begins when code is being pushed to the main branch. It will build and update the documentation, pull “gh-pages” branch and publish changes, and eventually trigger an update in the dedicated web page.
This is a shell script running on the CI pipeline
Eventually, a lovely documentation website is created, automagically, each time the main branch updates.
A word on security
For open source projects, it is important to notice what can happen in pull request branches where the CI carries privileged credentials.
One option most CI providers offer — is to turn off the build for forked pull requests. We find this solution may create difficulty for contributors.
Our answer to this issue was to grant our documentation user, Alvy, limited privileges, making sure it is not able to alter any of the production branches by applying protected branches policy.
Alvy is also not a member of our developers group, so it can’t clone, pull or fork any of our private repositories.
