DEV Community: igaurab

How to write a good function?

igaurab — Sun, 30 May 2021 11:02:12 +0000

Here are my 3 things to look out for while writing a good function. The code examples are given in python but the concept applies across all the programming languages. If you have any other ideas/strategies please mention them in the comments.

Don't Trust The Inputs

Look at the code below and think about what can go wrong.

def process_date(str_date):
    """
       This takes date in format dd/mm/yyyy and returns
       a dict of format {'y':2000,'m':10,'d':19 } as output
    """
    d,m,y = str_date.split('/')
    value = {'y':y,'m':m,'d':d}
    return value

At first glance, the code seems to work fine. If you run the function

process_date(str_date = 10/20/2000).

Then the output of the function will be:

{'y' : 2000,'m' : 20, 'd' : 10}

The function returns an output so everything seems to be working right? But there is a logical error. Months can never be greater than 12. The same goes for days and years. Apart from that what if the user passed negative values-1/-1/-1? Also, what if the user provided an empty string?

Here, we made a mistake of trusting the inputs. We should never trust the inputs. Be skeptical about the parameters and think hard about the edge cases. Make sure to sanitize your input before you perform any computation on them.

Fail Loudly and Clearly

What if you change the format of the date? From 10/20/2000 to 10-20-2000. This would completely break your code.

So, when the input is not what we want them to be, we want to notify the user about this issue. And if we have to fail, choose to fail loudly and clearly. The above error message is quite not clear compared to the one below, which clearly mentions that the issue is because of the input format of date supplied

regex_date_format = "^\d{1,2}/\d{1,2}/\d{4}$"
if not re.match(regex_date_format, date_str):
    raise ValueError(
        f"str_date: {str_date} should be of the format dd/mm/yyyy "
    )

Also, Most of the time, we tend to simply return None if we get any error.

if error:
    return None

if error:
    return None

some code

return result

This especially causes issue while debugging the program. In above dummy program, if we get a None as output, then which error in particular gave us the None value?
So, being loud and clear about the errors that occurs in program helps other developers and users of the function to understand what it is that is causing the issue/error.

Be consistent with return type

One thing I like about statically typed language is their consistency. If you are using a function then you'll know if that will return an array or a dict or an string etc. This allows us to process the output in some consistent manner and also avoids confusion and bugs in the program.

def return_something( input ):
    if error:
        return 'Error connecting to the server'
    code

    return {"data":"Hello world"}

Suppose someone uses this function in the following way:


response = return_something(inp)
data = response['data']

Here, the code breaks if there is any error while connecting to the server. The right way of checking it would be

response = return_something(inp)
if isinstance(response, str):
    handle_error
data = response['data']

The other way to write the same function would be:

def return_something( input ):
    if error:
        return {"error": 'Error connecting to the server' , "data": "" }
    code

    return {"data":"Hello world", "error": "" }

In both cases we get the same fields, this helps us be consistent with the way we process the data further in out code, and should not worry if we get a string or an array etc.

response = return_something(inp)
data = response['data']
error = response['error']

if error:
   handle_error

if data:
   do_something

This increases the code readability also. In the first example, one could wonder, why is it that we are handling the error if the instance is a string. Whereas in the second implementation it's clear that any response contains two fields the data and error and if we get any error we can do some error handing.

Please provide your feedback

Dockerfile good practices [NOTE]

igaurab — Tue, 04 May 2021 08:58:12 +0000

This is my note from this this talk on Dockerfile good practices

Areas of improvements

Incremental build time
Image size
Maintainability
Security
Consistency / Repeatability

Incremental build time

Making build cache your friend

Order is important: if you make changes to any line or any stage of your dockerfile then subsequent stages cache will be busted. So, order your steps from least to most frequently changing steps to optimize caching.

Let's look at this sample dockerfile

FROM ubuntu:18.04
COPY . /app
RUN apt-get update
RUN apt-get install openjdk-8-jdk

This dockerfile copies the application files immediately after the start. Because caching is based on previous steps, whenever something changes in that content, all the steps after the copy has to be invalidated. So, the cache will have to be busted and the steps below should run again.

This is a problem here, since if you want to change your application code, and want to build your image reflecting the latest change, you'll have run all the commands below the COPY command.
A better way here, would be to run the COPY command at the last.

FROM ubuntu:18.04
RUN apt-get update
RUN apt-get install openjdk-8-jdk
COPY . /app

Only copy what's needed Avoid COPY . if possible. When you are copying files into your image make sure you're very specific as to what you want to copy, because any changes to files you're copying will bust the cache
Identify cacheable units Sometimes you want things to be cached together. Identify cacheable units. For example change this

RUN apt-get update
RUN apt-get -y install openjdk-8-jdk

RUN apt-get update \

 && apt-get -y install \
     openjdk-8-jdk

This prevents using an outdated package cache.

Fetch dependencies in a separate step: This is also about identifying the cacheable units.

Reduce Image size

Remove unnecessary dependencies: Don't install debugging tools and other unnecessary dependencies. You can also use the --no-install-recommends flag. You don't want to deploy your build tools into production, as you will not need them at runtime.
Remove package manager cache: You don't need the cache after installing the packages. It's good to remove them as well

RUN apt-get update \ 
    && apt-get -y install --no-install-recommends \ 
    openjdk-8-jdk \ 
    && rm -rf /var/lib/apt/lists/*

Maintainability

Use official images where possible: Official images are pre-configured for container use and built by smart people. It can save you a lot of time in maintenance. This also allows you to share layers between images, as they use exactly the same base image.
For the above sample Dockerfile instead of using debain and installing the dependencies simply start your base image from FROM openjdk:8
Use more specific tags: The latest tag is a rolling tag. Be specific to prevent unexpected changes in your base image.
Look for minimal flavors Maybe you don't need all the things that is in the bigger variants.

REPOSITORY  TAG             SIZE
-----------------------------------------
openjdk     8               624MB
openjdk     8-jre           443MB
openjdk     8-jre-slim      204MB
opendjk     8-jre-alpine    83MB

Reproducible

The dockefile as a blueprint of your image, source code the source of truth for your application

Make the dockerfile your blueprint

It describes the build environment
Correct versions of build tools installed
Prevent inconsistencies between environments
There may be system dependencies

Multi-stage builds

Use Cases

Separate build from runtime environment
Slight variations on images (DRY)
Build dev/test/lint/ specific environments
- builder: all build dependencies
- build: builder + build artifacts
- cross: same as build but for different envs
- dev: builder + dev/debug tools
- lint: minimal lint dependencies
- test: all test dependencies + build artifacts to be tested
- release: final minimal image with build artifacts
Delinearizing your dependencies (concurrency)
Platform specific stages

When you name a stage you can only build that stage.

FROM image_or_stage AS stage_name

$ docker build --target stage_name

Further Resources

How to find the name of the package which includes your missing header file

igaurab — Fri, 02 Apr 2021 10:20:57 +0000

While I was installing my dwm build, i got a couple errors like the one shown in figure above. The header files which the dwm build needed were missing. The problem here is different linux distributions contains these header files under different package names. This solution works for debain or apt package manager.

Solution

The apt-file can be used to search for the package name where the header file is located. apt-file is not installed by default.

sudo apt install apt-file

Once we have installed the apt-file we can simply look for the name of the package where the header file is located. The name of the package I needed to install was libxinerama-dev Once we have the name of the package we can simply install it using apt.

sudo apt install libxinerama-dev

After that try to compile the file again and repeat the process until you are done.