My code, My Pride — Part 1

Write Clean Code and you can sleep well at night!

For who?

This article is very suitable for those who are willing to prove themselves as a CLEAN CODER and they are in very beginning stage of practicing clean code

WRITING IN PYTHON 🐍 ASPECTS

Yes, here I am going to explain the way I am practicing clean code and proud myself.

Four things make your coding practice, very clean

1. Use a coding standard
2. Auto documentation
3. File & Folder structure
4. Testing

Practice #1: Use a coding standard

All programming languages has its own coding style and standard.

Why coding standard?

When you are working with a large team (for startups 1+ team), your code must be in standard structure, so that, anyone can understand the code logic easily.

If you are a solo programmer for the project, even after a long time, if you review your own code it will give you clear idea about the logic

How to apply coding standard?

In Python world there are two standards are very popular which gives you the clean guidance on writing code in very standard manner. They are

1. PEP8 - https://www.python.org/dev/peps/pep-0008/
2. Google Style guide — https://google.github.io/styleguide/pyguide.html

There are some differences between PEP8 and Google style guide. PEP8 is the old one exclusive for Python development, most of the open source projects using PEP8 style guide. (I personally prefer PEP8 which is simple & easy to adopt than Google style guide)

How style guide help you?

The style guides explain you Correct and Wrong approach of writing of each cases.

For example, Tab or Space is a commonly asking questions by Python developers. This style guide will give you the answer for that simple question.

Here is the answer from PEP8 style guide

Source: https://www.python.org/dev/peps/pep-0008/#tabs-or-spaces

Practice #2: Auto documentation

The next big thing in your Clean code practice is Documentation.

Documentation is a Love letter that you write to your future self

As Python is using for both Webapp development and Backend development I am using two different Documentation

1. API Documentation
2. Module Documentation

Why auto documentation?

Most of the developer don’t write a documentation separately because of the time and effort to maintain document is more than development. So, auto documentation will help the developer to create the document as the comment on their code base. The auto document tool will create the beautiful HTML based document.

API Auto Documentation

There is a popular tool called Swagger which is the commonly using interface tool for delivering any API documentation.

Here is a detailed article about Swagger Flask integration

Automated Swagger API Doc with Flask Restful

How to create API Auto documentation?

It is so simple, to create the documentation for your API.

Here is my example

@pipeline_blueprint.route("/execute", methods=["POST"])
def execute_dag_pipeline():
    """
    Execute a pipeline
    ---
    tags:
      - pipeline
    parameters:
      - in: header
        name: Authorization
        description: Bearer <token>
        type: string
        required: true
      - in: body
        name: request
        description: Get config request body
        schema:
            type: object
            required:
                -data
            properties:
                pipeline_name:
                    type: string
    """
    logger.info("Started Triggering pipeline")
    ...

There are three main sections in the documentation

1. Description
2. Tags
3. Parameters
4. Responses (optional)

In the description part, we can add the information about the REST endpoint. The Tags are the used to show the endpoint in a collection.

Parameters are used to, how the user/developer can pass the input to the endpoint. There are four places, we can capture the parameters

1. Header — used to pass the credentials and JWT tokens
2. Body — used to pass the large number of requests in JSON/XML
3. Path (url path) — URL Parameter to pass the short things like ID
4. FormData — used to send files

There are some Swagger tools which can read these documents from your code and create the HTML based beautiful Swagger UI.

Try these libraries

flask-swagger

flask-swagger-ui

In Part 2, I’ll write more on Folder structure & Testing.

Thanks for reading!