Non-automatic style formatting

Comments

Bad Comments: Example of a comment that doesn’t make sense

# The estimated stock room size minus the rented space 
screen_time = 23 * 1.10

Bad Comments: Example of commenting gone overboard

# Reading in the cereal dataframe
cereal_dataframe = pd.read_csv('data/cereal.csv')

# Saving the cereal dataframe's columns as cereal_columns
cereal_columns = cereal_dataframe.columns 

cereal_dataframe.head() # Displaying the first 5 rows of the cereal_dataframe

Good Comments: Example of a useful comment

# Obtaining the cereals with calories between 130 and 150
cereal_dataframe[(cereal_dataframe['calories'] >130) & (cereal_dataframe['calories'] <150)]

We’ve learned about some tools that can help format and standardize our code, such as white space and indentations, but what about the things that a formatter can’t automatically change?

Let’s start with how we write comments.

Comments are important for understanding your code.

While docstrings cover what a function does, your comments will help document how your code achieves its goal.

python.org has some strong opinions about how comments should be written, and the first thing they mention is that our comments should reflect what the code is doing.

It sounds easy enough, but when working on projects that are constantly changing, it’s easy to change the code but forget to change the comments which do not affect the output of the code.

In cases like this, it’s better that our code has no comments than comments that contradict it.

It’s also important that comments add to the understanding of our coding instead of simply commenting for the sake of commenting.

Not all code needs a comment, especially if it’s redundant for understanding what the code does.

Guidelines according to PEP8 and python.org:

• Comments should start with a # followed by a single space.
• They should be complete sentences. The first word should be capitalized unless it is an identifier that begins with a lower case letter.
• Comments should be clear and easily understandable to other speakers of the language you are writing in.
• For block comments, each line of a block comment should start with a # followed by a single space and should be indented to the same level as the code it precedes.

Here are some basic guidelines according to PEP8 and python.org that are recommended when writing comments:

• Comments should start with # followed by a single space.
• They should be complete sentences.
• The first word should be capitalized unless it is an identifier that begins with a lower case letter.
• They should be clear and easily understandable to other speakers of the language you are writing in.
• If you are using block comments, each line of a block comment should start with a # followed by a single space and should be indented to the same level as the code it precedes.

BAD comment

# adding 6.99 
cost = cost + 6.99 

Better comment

# Accounting for shipping charges
cost = cost + 6.99 

BAD comment

x = 0

# This code iterates over the numbers 1 to 5 each time adding the number
# to the variable x to get a sum of the numbers from 1, 2, 3, 4, and 5. 
for i in range(1,5):
    x = x + i

Better comment

x = 0

# Sum up the values 1 to 5 
for i in range(1,5):
    x = x + i

Here is an example of a bad comment where we say “adding 6.99” to the cost variable. This comment doesn’t tell us why we are doing this operation. A more reasonable comment would be to correct the capitalize the comment and explain that we are adding 6.99 to the variable cost to account for shipping charges.

Code that is concise is preferred over long-winded explanations. In this next example case, there is no need to write a comment this long when something short like “Sum up the values 1 to 5” does the job.

When writing comments, it’s important to make sure they are meaningful, concise, and are a supplement to the understanding of your code.

Naming convention

Some common variable naming recommendations:

• Variable names should use underscores
• Variable names should be lowercase

Fine

lego

Fine

lego_themes

Fine

lego_df

Not Recommended

lego_DF

Not Recommended

LEGO

Not Recommended

legothemes

Python naming convention is somewhat inconsistent, as stated on Python.org’s website

That being said, it’s useful to try to set consistent standards which helps the Python community and will help you keep track of your code at a later time.

Some common variable naming recommendations are as follows:

• Variable names should use underscores
• Variable names should be lowercase

You could use the names lego, lego_themes, lego_df, but we advise again things like lego_DF, LEGO or legothemes.

Variables without Keywords

Don’t Do This

list = []

Or This

def tuple(argument):
    return 

Or This

str = 4
type = 67 * str

Something you should not name your variables are Python keywords.

This will create a multitude of problems for you.

For example, If you did name a variable with the specific keyword, the next time that you attempt to use that keyword for its intended functionality, an error will be thrown because it will try to use your variable instead!

Meaningful Names

a = 100 
b = 23
c = 0.56

d = a + b
e = c * d

apples = 100 
bananas = 23
fruit_price = 0.56

fruit_total = apples + bananas
cost = fruit_price * fruit_total

Just like how we use comments to explain our code, it’s good coding style to name your variables thoughtfully and in ways that help make your coding more “readable”.

Naming your variables helps others (and future you) make sense of the instructions you are writing for the computer.

For example, let’s try writing the code here again but with variable names that are a bit more descriptive.

Giving these new variables names, we can follow a bit more of the reasoning behind the calculations.

Concise Names

mass_of_the_object_in_motion = 45
the_acceleration_of_the_object_in_motion = 1.8

force_acting_on_an_object = mass_of_the_object_in_motion * the_acceleration_of_the_object_in_motion

mass = 45
acceleration = 1.8

force = mass * acceleration

Similarly to how variables named without meaning makes code readability difficult, the same can be said about variables with excessively long names.

You want to be efficient yet understandable.

In this example, we can see that the second body of code is much easier on our eye, and it takes much less effort to understand what our code is trying to convey.

Let’s apply what we learned!