Dobre praktyki tworzenia nazw

Phil Karlton

There are only two hard things in Computer Science:

 

  1. cache invalidation
  2. naming things.

 

Używaj nazw przedstawiających intencje

Przykłady:

$d; // czas trwania w dniach
$elapsedTimeInDays;
$list; // lista kategorii
$categories;
$t; // czas modyfikacji (timestamp)
$modificationTimestamp;

Przykłady:

function filterOrders()
{
    $orders = [];
    foreach($this->getAll() as $order) {
        if($order->status == 4)
            $orders[] = $order;
    }
    return $orders;
}
function getPaidOrders()
{
    $paidOrders = [];
    foreach($this->getAll() as $order) {
        if($order->isPaid())
            $paidOrders[] = $order;
    }

    return $paidOrders;
}

Unikaj niepotrzebnego nadmiaru informacji

Przykład:

class ProductList {

    public function numberOfProducts(){}

}
class ProductList {

    public function size(){}

}

Przykład:

class CategoryDataObject {

}

class CategoryEntity {

}
// może być w odpowiednim namespace
class Category {

}

Promuj jasność nad zwięzłością

Są wyjątki ! (kontekst ma znaczenie)

Będziesz czytał kod więcej razy niż go pisał.

Przykład

class ImportProductsCommand {

    public function execute() {
        $this->initializeEntityManagers();
        $this->truncateProductsTable();
        $this->importProductsFromLegacyDatabase();        
    }

}
class ImportCommand {

    public function execute() {
        $this->initialize();
        $this->truncate();
        $this->import();        
    }

}

Ale nie zawsze

$appointmentList

$calendar
$companyPerson

$employee
$textCorrectionByEditor

$edit

Szanuj specyfikę języka/frameworka

Nie używaj negatywnej logiki

Przykład

class Product {

    public function isNotEnabled();

}
class Product {

    public function isEnabled();

}
if(!$user->isNotAdmin()) {}
 
if(!$product->isNotEnabled()) {}

Twórz nazwy które można wymówić

Przykład

class DtaRcd {

    private $modDMY;

    public function rcdInt();

}
class Account {

    private $modificationDate;

    public function getInternalId();

}

Używaj jedno słowo na jedną pojęcie 

Przykład

class UserRepository {

    public function fetchAll();
    public function retrieveActive();
    public function getByOrganization();
    public function findOneById();

}
class UserRepository {

    public function findAll();
    public function findActive();
    public function findByOrganization();
    public function findOneById();

}

Przykład

$repository->find...();

$entity->get...();

$provider->fetch...();

$storage->retrieve...();

Uwzględniaj kontekst

class Order {
    private $street;
    private $city;
    private $postCode;
    private $state;
}
class Order {
    private $adrStreet;
    private $adrCity;
    private $adrPostCode;
    private $adrState;
}
class Order {
    private Address;
}

Korzystaj z dziedziny problemu

// mamy zamówienie
$order;
 
// w warstwie domenowej 
// przyjęcie zamówienia może wyglądać tak:
$shop->placeOrder($order)
 
// w warstwie infrastruktury
// jego zapis może być taki:
$em->persist($order);

Im bliżej kod jest dziedziny problemu tym bardziej powinien zawierać nazwy z tej dziedziny.

Przykłady kiepskich nazw

$foo
// nie przedstawia intencji

$data
// zbyt ogólna

$a
// za krótka 

$productsEditedBySuperAdminUsers
// za długa

$mod
// niejednoznaczna 

class InvoiceManager {}
// nieokreślona

$state
// w złym kontekście

$products_list
// inna konwencja

Porady od zawodowych pisarzy

Dlaczego warto ?

  • Są przydatne i nie dotyczą wyłącznie tworzenia nazw
     
  • Pisarze istnieją od wieków, programiści tylko od dekad
     
  • Ich porady są lepiej napisane i bardziej zabawne

Stephen King

programownie w zespole

Write with the door closed, rewrite with the door open

Anne Rice

hardware developera

I find the bigger the monitor, the better the concentration

Neil Gaiman

review feedback

When people tell you something’s wrong or doesn’t work for them, they are almost always right.

When they tell you exactly what they think is wrong and how to fix it, they are almost always wrong

Parę słów na temat komentarzy

Dobry kod nie wymaga komentarzy 

// sprawdzenie czy pracownik jest w wieku emerytalnym
if(
    ($employee->gender=='F' && $employee->age > 60) 
    || 
    ($employee->gender=='M' && $employee->age > 65)
)

if($employee->isInRetirementAge())

Dobre komentarze

  • Komentarze prawne
  • Docblock
  • Ostrzeżenie o konsekwencjach
  • Wyjaśnienie (np. skomplikowany regexp)
  • Komentarze TODO

Złe komentarze

  • Komentarze HTML
  • Znaczniki pozycji
  • W klamrach zamykających
  • Duplikowanie informacji
  • Automatycznie generowane komentarze (IDE i inne narzędzia)

Jak ulepszać swoje zdolnośći językowe

Czytaj książki

Graj

Wykorzystuj słowniki

Słownik wyrazów bliskoznacznych - synonimy

(thesaurus)

Szlifuj swój angielski

Podsumowanie

  1. Tworzenie nazw jest trudne !
     
  2. Czytaj dobry kod (GitHub)
     
  3. Rozwiń umiejętności językowe: czytaj, opowiadaj, graj
     
  4. Spróbuj coś napisać
    1. programuj !!!
    2. komentarze
    3. własny blog 
    4. książka

THX

Made with Slides.com