Introduction to Documentation and Code Linting

This blog mainly focuses on two concepts which are a bit underrated. One is code linting and other is live documentation.

Let's first understand the meaning of these two concepts before we dive into the implementation.

Linting

• Linting is the process of running a program that will analyse code for potential errors.

• Simply put, it is the process of checking the source code for Programmatic as well as Stylistic errors. This is most helpful in identifying some common and uncommon mistakes that are made during coding.

• A Lint or a Linter is a program that supports linting (verifying code quality). They are available for most languages like JavaScript, CSS, HTML, Python, etc..

• Running a lint program over your source code, helps to ensure that source code is legible, readable, less polluted and easier to maintain.

• It helps you find :

  1. formatting discrepancies
  2. find non-adherence to coding standards and conventions
  3. pinpoint possible logical errors in your program

Linting tools usage:

• Linting tools can be configured with other tools like git pre commit hook and husky, to ensure that the linting is done of the code that is being committed to a certain repository.

• This will make sure that coding standards are maintained and code is formatted and language specific best practices are adhered before code is committed to the repository.

• Engineers will be able to make the commit only if the said coding standards are met.

ruff - An extremely fast Python linter and code formatter, written in Rust.

Documentation - https://pypi.org/project/ruff/

Documentation using MakeDocs

    “Code is more often read than written.”

    — Guido van Rossum

• Whenever you are using a library, you look for examples or official documentation on how to do something specific.

• Software documentation is a crucial part of a working software.

• Documentation is crucial because it can assist users understand how to use your software, it can provide developers and other technical stakeholders with information about the technical aspects of your software.

• Well-written software documentation can help improve the overall quality and user experience of your software.

• Makedocs helps you in creating "auto-generated documentation". It links your information between code and documentation pages.

• Using Makedocs, you can create project documentation with less efforts conveniently and effectively.

Implementation

I have created a sample project which helps you in understanding the basics of code linting and live documentation.

Source Code : encode_decode

Documentation : Encode Decode Docs

The documentation is always live and you can access it anytime.

Please go through the following resources that will help you in understanding the concepts and the implementation better.

1. https://pypi.org/project/ruff/
2. https://realpython.com/python-project-documentation-with-mkdocs/

Happy Learning !!!