Unit1-03: Style & Comments

Lesson

• when you create programs, you are not creating them just for the computer

  • you have 2 audiences:

    • computer

    • every other developer that has to look at your code, including you!

  • your program source files (i.e. code, etc.) need to be computer and human friendly

• to summarize the PEP8 style guide for Python (now called pycodestyle):

  • configure Codespaces to use 4 spaces per indentation level

    • spaces are the preferred indentation method

  • codespaces should be limited to a maximum length of 79 characters per line

  • comments should be complete sentences. The first word should be capitalized.

  • function names should be lowercase, with words separated by underscores as necessary to improve readability

  • variable names follow the same convention as function names:

    • ALWAYS use a proper name for a variable, NEVER something like "i"

    • ex: num_students = 30, distance = 59.4, user_name = "Guest"

  • constants are written in all CAPS: 

    • i.e. MAX_OVERFLOW = 100, HST = 0.13, BRAND = "Nike"

  • always include a shebang at the top of your code:

    • it defines where the interpreter for Python3 is located on your computer. (Even though we are using a virtual IDE (Codespaces), it s a good habit to get into.)

    • #!/usr/bin/env python3

  • after the shebang, ALWAYS include a header comment with your name, program creation date and at least one (1) sentence explaining what the *.py file does

    • #!/usr/bin/env python3

    • # Created By: Your Name

    • # Date: Month Day, Year

    • # Write what this program does.

• read about "How to Write Comments in Python"

  • comments are not executed

  • comments in Python begin with #

  • comments are made to help all programmers who will look at the code better understand what the code is intended to do

  • if comments cannot be properly updated with the code base, it is better to not include a comment rather than write a comment that contradicts or will contradict the code.

• watch "Why You Should Use Python if __name__ == "__main__": ..."

  • always use the following: 

    • if __name__ == "__main__"

    • it tells me which file is the script that we will run or launch

• watch Comments & Style in Python

  • use Black on all your python code to ensure you are following the rules 

    • black --diff ./*.py

    • or just

    • black ./*.py

  • how do you know it worked?

    • look for something like:

    • All done! ✨ 🍰 ✨

    • 2 files would be left unchanged.