How To Comment Your Python Code as a Data Scientist

By neub9
3 Min Read

Image generated by DALL·E 3

Data scientists are placed in a unique and exciting position. While their job in the modern era requires them to use the programming language, they also need to consider various business aspects. This is why the Python code used by Data Scientists often reflects a storytelling approach to solving business problems.

The environment for data scientists is also remarkable, as they use the Jupyter Notebook IDE, which allows for an excellent way to experiment with data manipulation and model development. This calls for a different way of coding, which includes the activity of commenting to explain the code.

In this article, we will discuss Python code commenting in the context of data science and provide tips to improve this activity, bringing value to anyone who reads the code.

Types of Commenting

Before moving further, it’s important to understand two different types of commenting in Python:

  • Single-line commenting: Uses the ‘#’ notation in the code for a simple explanation of the code.
  • Multi-line commenting: Employs triple quotes and is used to explain complex processes or activities.

General Tips for Commenting

Some general best practices for commenting include:

  • Placing the comment in a separate line directly above the code you want to explain to increase readability.
  • Consistency in the commenting style throughout the code.
  • Avoid using jargon and technical terms that may not be understood by the audience.
  • Only comment if it’s adding value and avoid explaining the obvious.
  • Maintain and update the comment if it becomes irrelevant.

Specific Tips for Data Scientists

For data scientists, the coding and commenting activity is different from that of a software engineer or web developer. Here are some tips specific to data scientists:

  1. Use Commenting to Clarify Complex Processes or Activities: Explain the intention behind the code, especially if it involves many experimental processes.
  2. Having a Commenting Standard: Create a standard structure for comments, particularly for functions.
  3. Use Comments to Help the Workflow: Use comments to help the team understand the workflow or what needs to be done next.
  4. Implement the Markdown Notebook Cells: Use Markdown within notebook cells to further explain the code and add tables, images, LaTeX, and more.

Commenting is an integral part of the data scientist’s activity as it helps clarify what happened with the code. These tips provide guidelines for data scientists to effectively comment their Python code.

Share This Article
Leave a comment

Leave a Reply

Your email address will not be published. Required fields are marked *