naming conventions and code formatting

There are only two hard things in Computer Science: cache invalidation and naming things

Phil Karlton

Naming conventions

a = b * c;

vs

weekly_pay = hours_worked * hourly_pay_rate;

Naming conventions

Why?

 

  • Reduce the effort needed to read and understand source code

 

  • Enable code reviews to focus on more important issues than arguing over syntax and naming standards.

 

 

Brevity

Reasons

 

  • early source code editors lacking autocomplete

 

  • early low-resolution monitors with limited line length (e.g. only 80 characters)

 

  • much of computer science originating from mathematics, where variable names are traditionally only a single letter

Word conventions

 

  • camelCase
  • PascalCase
  • snake_case
  • kebab-case

Python conventions

construct convention
Class CapWords
Functions lowercase
Methods lowercase
Type variables CapWords
Constants UPPERCASE
Package lowercase
Module lowercase

Python conventions

_single_leading_underscore: weak "internal use" indicator. E.g. from M import * does not import objects whose name starts with an underscore.

Python conventions

>>> class Test(object):
...     def __mangled_name(self):
...         pass
...     def normal_name(self):
...         pass
>>> t = Test()
>>> [attr for attr in dir(t) if 'name' in attr]
['_Test__mangled_name', 'normal_name']

Any identifier of the form __spam (at least two leading underscores, at most one trailing underscore) is textually replaced with _classname__spam, where classname is the current class name with leading underscore(s) stripped.

Python conventions

PEP8

  • PEP 8 is a document that provides guidelines and best practices on how to write Python code. It was written in 2001 by Guido van Rossum, Barry Warsaw, and Nick Coghlan. 
  • PEP stands for Python Enhancement Proposal, and there are several of them. A PEP is a document that describes new features proposed for Python and documents aspects of Python, like design and style, for the community.

Python conventions

PEP8

https://www.python.org/dev/peps/pep-0008/

https://development.robinwinslow.uk/2014/01/05/summary-of-python-code-style-conventions/

Formatting

Black

Formatting

Black (Why?)

https://github.com/django/deps/blob/master/accepted/0008-black.rst

Formatting

Black

  • Black is the uncompromising Python code formatter. By using it, you agree to cede control over minutiae of hand-formatting. In return, Black gives you speed, determinism, and freedom from pycodestyle nagging about formatting. You will save time and mental energy for more important matters.

 

  • Blackened code looks the same regardless of the project you're reading. Formatting becomes transparent after a while and you can focus on the content instead.

 

  • Black makes code review faster by producing the smallest diffs possible.

Formatting

isort

https://github.com/timothycrosley/isort

Formatting

isort + black in our CI pipeline

Rafał

1. Oddzialenie enterami ściany tekstu  black!
wcięcia,
długość linii		 black!
3. help_texty w  modelach tak!
4. dodawanie docs stringów do metod, klas https://confluence.3bpo.com/display/IG/Dokumentowanie+kodu
5. dodanie komentarza jak powyżej
6. unikanie skrótów myślowych tak ale..

Clean Code

Clean Code

Use intention revealing names

The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its intent. 

int d; // elapsed time in days
int elapsedTimeInDays;
int daysSinceCreation;
int daysSinceModification;
int fileAgeInDays;

Clean Code

Avoid disinformation

Avoid leaving false clues that obscure the meaning of code.

Clean Code

Make meaningful distinctions

Avoid leaving false clues that obscure the meaning of code.

class ProductInfo  

class ProductData


void getActiveAccount()

void getActiveAccounts()

void getActiveAccountsInfo()

Clean Code

Use pronounceable names

If you can’t pronounce it, you can’t discuss it without sounding like an idiot. “

Date genymdhms;

Date modymdhms;

Int pszqint;

Clean Code

Use searchable names

Single-letter names and numeric constants have a particular problem in that they are not easy to locate across a body of text.

Clean Code

Avoid encodings

PhoneNumber phoneString;
client_names_list = ['John', 'Jack']
client_names: List[str] = ['John','Jack']

Clean Code

Classes

Classes and objects should have noun or noun phrase names like Customer, WikiPage, Account, and AddressParser. Avoid words like Manager, Processor, Data, or Info in the name of a class. A class name should not be a verb.

Clean Code

Methods

Methods should have verb or verb phrase names like postPayment, deletePage, or save.

  • Reread your code before submitting
  • Read quality code on github 

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”

Martin Fowler

Thank You

Made with Slides.com