When looking at many major open-source projects, we see extensive documentation on almost all methods or API calls (e.g). As a small team or one person, it would be nice to have similar output, without a large amount of work required. Luckily, most of the documentation used by those projects is auto-generating. There are tools that scans your code and comments to generate documentation that can be exported in different formats such as HTML. I used the tool to add this document to my CLI project.
When getting information for your program from an external source, it is important to validate the information to make sure it is in the expected format and has correct values. This is especially true when getting information from the internet, where trust is less assured. Input and data validation can be used to prevent security issues, such as SQL injection and buffer overruns or catch and correct/fail safely when an error occurs. For example, if a function has an unexpected edge case that causes garbage output, validation would raise an exception instead of executing the garbage.
A frequent issue I have encountered while working with in-house development teams is that the application works in the development environment, but fails to run or operate strangely in the production environment. This can usually be attributed to drift between development and production. During development, the developer’s environment tends to accumulate extras (gems, workarounds, and scripts) that do not follow into production. Additionally, developers usually have difficulty fixing production issues due to the missing accumulated extras or differences in environment layouts. Virtual machines are only able to provide limited relief to this problem as long-lived virtual machines would accumulate drift as well.
In the past, applications were written to fit a set of machines in specific and often unique configurations. The classic example was the mainframe systems and their purpose-driven applications. It took teams of machine administrators to ensure the desired state and troubleshoot errors as they occur on the machines. In the past, there were efforts to standardize and make applications cross-compatible, such as the POSIX standard, high-level programming (non-assembly) languages, and interchangeable hardware components. This led to the computer hardware of today. These parts have componentized the motherboards, power supplies and hard drives are not repaired, but replaced and sent to extremely specialized sites for further processing. This moved administrators of those days from machine-specific to server/OS level administration. Freeing the new admins to work on the higher-level task, that today’s system admin (such as myself) work on.