Good code is primarily written for humans, not for computers. Sure, it all gets compiled down to computer-readable instructions eventually, but for good team collaboration and feature extensibility, code should be well-documented. Here’s how we define what that means at Crema:
Comments in code: most programmers spend a considerable chunk of their day reading and trying to understand code - which can include code written by oneself in the past. We strive to leave good comments - hints and explanations for others and ourselves and make the purpose and structure of our code as transparent as possible, in order to shorten the time it takes to get up to speed.
Living Documentation: from Wikis, to shared documents, to Markdown and plain old README files, a repository of living documentation is a great way to “explain” a codebase to anyone, technical or non-technical, who inherits it or has to alter it in the future. It is also a great way for teams of multiple developers to collaborate.
Documentation Tooling: we leverage a number of automated tools to generate up-to-the-minute accurate documentation for our codebases. For instance, we use Storybook to generate visual catalogs of React Components, promoting reusability and making it easy to visualize a UI element in isolation. We also rely on tools like Swagger and GraphiQL (pronounced “graphical”) to create interactive browser-based API documentation, which is indispensable for development teams that are often separated into front-end and back-end.