Skip to content

Latest commit

 

History

History
94 lines (67 loc) · 2.81 KB

11.Writing_comments.md

File metadata and controls

94 lines (67 loc) · 2.81 KB

Writing comments

Introduction

When you write code in python it is important for it to be understandable by other people, and in order to reach this effect you can give variables and functions appropriate names, you can also help person who reads your code understand it by writing comments.

In this guide you will learn:

  • Importance of commenting
  • How to write comments
  • How not to write comments

Importance of commenting

An essential component of any program is comments. They might take the form of inline explanations that clarify complicated functions, module-level docstrings, or both. Let's examine the significance of code comments before delving into the various forms of comments. Think about the next two situations where a programmer choose not to comment their code:

When you're writing code for yourself

Developers often forget what their code looks like when they're under a lot of pressure. Writing comments as you go is a great way to prevent this from happening.

When you're writing code for someone else

Using comments throughout your code can help other developers. Comments help other devs skim through your code and gain an understanding of how it all works very quickly. You can help ensure a smooth transition by choosing to comment your code from the outset of a project.

How to write comments

To write comment in python you simply have to put # before the text that you want to be commented, this part will be completely ignored by python:

print("hi")  # print("bye")

Output:

hi

how you can see #print("bye") part is ignored and doesn't influence output.
Comments must be short and to the point. Maximum 72 characters for inline comment is appropriate, if you surpass this value you should translate your comment to the next line.

Multiline comments

Unfortunately, in python, you can't make multiline comments like in other languages, instead you can add more #s:

# This is example
# of multiline
# commenting in python

there is another way of creating comment:

"""
this is another example
of multiline comment 
which is not really a comment
"""

this is string that is not assigned by any of the variables so it is ignored by pythin, but you have to be careful with these things, because sometimes, when you comment function or methods this way, it might confuse people who read your code.

How not to write comments

  1. Avoid D.R.Y. comments(D.R.Y. stands for "don't repeat yourself"), your comments mustn't be redundant. There is no need to comment pieces of code tht speak for themselves:
def foo():
    a = 0
    return a  # returns a
  1. Avoid comments that are trying to hide problems of your code.
  2. Avoid rude comments:
# This fucking code Sasha has written is yebala, needs to be fixed