Wie man Dinge gut benennt

Geschichte der gesprochenen Sprache und der Programmiersprache
Viele Empfehlungen zur Benennung von Variablen, Funktionen und Klassen
Einige Tipps und Tricks wie man daran herangehen kann gut Namen zu finden

Transcript

1. Wie man Dinge
   Wie man Dinge
   gut benennt
   gut benennt
   Naming things considered hard
   Naming things considered hard
   Symfony Live Berlin 2018
   Symfony Live Berlin 2018
   

   View Slide

2. Anne-Julia Seitz
   Anne-Julia Seitz
   Schreibe Software seit über 15 Jahren
   Beraterin und Entwicklerin bei PortZero GmbH
   Habe das meiste was ich zeige so gesehen
   

   View Slide

3. Geschichte der Sprache
   Geschichte der Programmiersprache
   Allgemeine Empfehlungen zur Benennung
   Empfehlungen zur Benennung von Variablen,
   Funktionen und Klassen
   Tipps und Tricks
   

   View Slide

4. Geschichte der
   Geschichte der
   Sprache
   Sprache
   

   View Slide

5. View Slide

6. Kontext
   Kontext
   

   View Slide

7. Bedeutung = Sache + Kontext
   Bedeutung = Sache + Kontext
   

   View Slide

8. Geschichte der
   Geschichte der
   Programmiersprache
   Programmiersprache
   

   View Slide

9. Binärcode
   Binärcode
   

   View Slide

10. Assembler
    Assembler
    .START ST
    ST: MOV R1,#2
    MOV R2,#1
    M1: CMP R2,#20
    BGT M2
    MUL R1,R2
    INI R2
    JMP M1
    M2: JSR PRINT
    .END
    

    View Slide

11. Höhere Programmiersprachen
    Höhere Programmiersprachen
    A:=2;
    FOR I:=1 TO 20 LOOP
    A:=A*I;
    END LOOP;
    PRINT(A);
    

    View Slide

12. Warum ist
    Warum ist
    Benennung wichtig?
    Benennung wichtig?
    

    View Slide

13. Empfehlungen
    Empfehlungen
    für Sprache
    für Sprache
    

    View Slide

14. Programmiere auf englisch
    Programmiere auf englisch
    unratsam:
    unratsam:
    gut beraten:
    gut beraten:
    $obst = "Apfel;Himbeere;Traube";
    $obstListe = explode(";", $obst);
    //Ausschließlich (amerikanisches) englisch, ohne Ausnahme!
    $fruits = "Apfel;Himbeere;Traube";
    $fruitList = explode(";", $fruits);
    

    View Slide

15. Benutze einfache Sprache
    Benutze einfache Sprache
    Incomprehensibilities
    Uncopyrightables
    Uncharacteristically
    Abstentious
    Predicate
    Supercalifragilisticexpialidocious
    

    View Slide

16. Vermeide Zungenbrecher
    Vermeide Zungenbrecher
    wie spricht man das?
    wie spricht man das?
    aussprechbar:
    aussprechbar:
    class DtaRcrd102 {
    private $genymdhms;
    private $modymdhms;
    }
    class Customer {
    private $generationTimestamp;
    private $modificationTimestamp;
    }
    

    View Slide

17. 1337 SP34K ist nicht cool
    1337 SP34K ist nicht cool
    n0pe:
    n0pe:
    am besten:
    am besten:
    UberController
    $obj->f1nd4ll3n3mi3s();
    $numb3r
    Only english without exceptions!1!11!!!
    

    View Slide

18. Benutze kein Unicode
    Benutze kein Unicode
    schlecht:
    schlecht:
    genauso schlecht:
    genauso schlecht:
    क = 1; कु ल = 0;
    जब तक क छोटा है 10 से {
    कु ल += क;
    }
    छापो कु ल;
    public enum Товары
    {
    Тетради = 2,Карандаши = 4,
    Всё = Тетради | Карандаши
    }
    

    View Slide

19. Wirklich, kein Unicode
    Wirklich, kein Unicode
    

    View Slide

20. Fluche nicht
    Fluche nicht
    schlecht:
    schlecht:
    gut:
    gut:
    $fuckYouId
    $controller->hellNo();
    // not even in your **** comments
    

    View Slide

21. Empfehlungen
    Empfehlungen
    für Code
    für Code
    

    View Slide

22. Versuche es kurz zu halten
    Versuche es kurz zu halten
    ProjectContractChargingPeriodProjectAccountReferenceVM
    $countriesFromAsiaWhereAreTheMostPlanesAndBoats
    $countriesFromAfricaWhereAreTheMostCars
    renderHTMLViewFromTemplateObject()
    

    View Slide

23. Faustregel für Länge
    Faustregel für Länge
    1 Buchstabe für Schleifenzähler
    1 Wort für Konditionen und Schleifenvariablen
    1-2 Wörter für Methoden
    2-3 Wörter für Klassen
    3-4 Wörter für globale Konstanten
    

    View Slide

24. Vermeide Abkürzungen
    Vermeide Abkürzungen
    undeutlich:
    undeutlich:
    gut:
    gut:
    SrvMgrInstanceDescriptorFactory
    $ctrl, $ctr
    $tmpl
    $list->srt();
    SrvMgrInstanceDescriptorFactory
    $controller
    $template
    $list->sort();
    

    View Slide

25. Akronyme in Großbuchstaben
    Akronyme in Großbuchstaben
    OK:
    OK:
    OKer:
    OKer:
    Pdf
    Url
    XmlHttpRequest
    PDF
    URL
    XMLHttpRequest
    

    View Slide

26. Nullwörter
    Nullwörter
    zu unspezifisch:
    zu unspezifisch:
    gut:
    gut:
    ConnectionManager, XmlHelper
    ObjectDataHandlerManagerBuilderHelperFactory
    $tmp, $temp, $data, $var, $array, $key, $index ...
    Connection
    XmlDocument,
    XmlNode
    

    View Slide

27. Lösche unbenutzten Code
    Lösche unbenutzten Code
    kann das weg?
    kann das weg?
    ja:
    ja:
    NewHandler
    $obj->buildContextFaster();
    // use the vcs!!1!11
    

    View Slide

28. Benutze suchbare Begriffe
    Benutze suchbare Begriffe
    unauffindbar:
    unauffindbar:
    gut zu finden:
    gut zu finden:
    for ($j = 0; $j < 34; $j++) {
    $s += ($t[$j] * 4) / 5;
    }
    const WORK_DAYS_PER_WEEK = 5;
    $realDaysPerIdealDay = 4;
    $sum = 0;
    for ($j = 0; $j < NUMBER_OF_TASKS; $j++) {
    $realTaskDays = $taskEstimate[$j] * $realDaysPerIdealDay;
    $realTaskWeeks = ($realTaskDays / WORK_DAYS_PER_WEEK);
    $sum += realTaskWeeks;
    }
    

    View Slide

29. Vorsicht bei Gleichheit
    Vorsicht bei Gleichheit
    XYZControllerForEfficientHandlingOfStrings
    XYZControllerForEfficientStorageOfStrings
    

    View Slide

30. Rechtschreibprüfung
    Rechtschreibprüfung
    eingeschaltet lassen
    eingeschaltet lassen
    

    View Slide

31. Sei Konsistent beim Stil
    Sei Konsistent beim Stil
    Stile:
    Stile:
    das Auge stolpert:
    das Auge stolpert:
    UpperCamelCase
    lowerCamelCase
    snake_case
    displayText_label_maxDiff
    public function setAccessArguments(array $access_arguments) {}
    

    View Slide

32. Bleibe bei einer Schreibweise
    Bleibe bei einer Schreibweise
    public function getUsername(): string
    {
    return $this->userName;
    }
    

    View Slide

33. Variablen
    Variablen
    

    View Slide

34. Benutze keine Ein-Buchstaben
    Benutze keine Ein-Buchstaben
    Variablen
    Variablen
    ohne Aussage:
    ohne Aussage:
    besser:
    besser:
    ok in Loops:
    ok in Loops:
    $t; // elapsed time in days
    $elapsedTimeInDays;
    // in einem for- oder foreach-loops
    for ($i = 0; $i < 10; $i++) {}
    // besser ein benannter index:
    foreach($cars as $carKey => $car) {}
    

    View Slide

35. Variablen werden nicht
    Variablen werden nicht
    inkrementiert
    inkrementiert
    zu ähnlich und uneindeutig:
    zu ähnlich und uneindeutig:
    gut:
    gut:
    $account1
    $account2
    $account
    $accountFromOtherCompany
    1
    2
    1
    2
    

    View Slide

36. Vermeide zusammengesetzte
    Vermeide zusammengesetzte
    Namen
    Namen
    kann gekürzt werden:
    kann gekürzt werden:
    kurz:
    kurz:
    $shipmentOrder
    $treeLeaf
    $order
    $leaf
    1
    2
    1
    2
    

    View Slide

37. Funktionen
    Funktionen
    

    View Slide

38. Benutze Verben als
    Benutze Verben als
    Funktionsnamen
    Funktionsnamen
    schlecht:
    schlecht:
    gut:
    gut:
    $list->refCount();
    $list->clear();
    $list->sort();
    $obj->addReference();
    

    View Slide

39. Versuche es kurz zu halten
    Versuche es kurz zu halten
    schlecht:
    schlecht:
    gut:
    gut:
    $list->getNumberOfItems();
    $list->count();
    

    View Slide

40. Aber nicht zu kurz
    Aber nicht zu kurz
    schlecht:
    schlecht:
    gut:
    gut:
    $list->verify();
    $list->containsNull();
    

    View Slide

41. Fragen für booleans
    Fragen für booleans
    schlecht:
    schlecht:
    gut:
    gut:
    $list->empty();
    $list->isEmpty();
    $list->contains($item);
    

    View Slide

42. Vermeide Redundanz mit
    Vermeide Redundanz mit
    Funktionsparametern
    Funktionsparametern
    schlecht:
    schlecht:
    gut:
    gut:
    $list->addItem($item);
    $handler->receiveMessage($message);
    $list->add($item);
    $handler->receive($message);
    

    View Slide

43. Vermeide Redundanz mit
    Vermeide Redundanz mit
    Empfänger-Objekt
    Empfänger-Objekt
    schlecht:
    schlecht:
    gut:
    gut:
    $list->addToList($item);
    $list->add($item);
    

    View Slide

44. Benutz kein
    Benutz kein And
    And oder
    oder Or
    Or in
    in
    Funktionsnamen
    Funktionsnamen
    schlecht:
    schlecht:
    gut:
    gut:
    $mail->verifyAddressAndSendStatus();
    $mail->verifyAddress();
    $mail->sendStatus();
    

    View Slide

45. Wähle ein Wort für ein Konzept
    Wähle ein Wort für ein Konzept
    holen:
    holen:
    erstellen:
    erstellen:
    löschen:
    löschen:
    fetch, retrieve, get
    create, insert, put, add
    remove, delete, prune
    

    View Slide

46. Klassen
    Klassen
    

    View Slide

47. Bevorzuge Hauptwörter
    Bevorzuge Hauptwörter
    nein:
    nein:
    ja:
    ja:
    Messanging
    Messenger
    

    View Slide

48. Benutze auch Namespaces
    Benutze auch Namespaces
    lang:
    lang:
    nutzt Namespaces:
    nutzt Namespaces:
    SystemOnlineMessage
    System\Online\Message
    1
    1
    

    View Slide

49. Tipps und Tricks
    Tipps und Tricks
    

    View Slide

50. Wenn nichts sich richtig anfühlt
    Wenn nichts sich richtig anfühlt
    Frage was es tun soll.
    Finde mehr über die Business-Domäne heraus.
    Frage einen Kollegen was er denkt wie es heißen
    kann.
    Schau auf GitHub nach ähnlichem Code.
    Entscheide für das offensichtlichste.
    

    View Slide

51. Eine kleine Formel
    Eine kleine Formel
    für Service-Klassen:
    für Service-Klassen:
    Nomen + Verb + “er”|“or”
    Nomen + Verb + “er”|“or”
    

    View Slide

52. Beispiele:
    Beispiele:
    ConfigurationBuilder
    QueryDumper
    RoutingStatePresenter
    FormDecorator
    VelocityResponseWriter
    

    View Slide

53. Sammlung Hauptwörter
    Sammlung Hauptwörter
    Attribute, Base, Bridge, Bucket, Chain, Collection, Configuration,
    Context, Command, Composite, Element, Entity, Exception, Field,
    Flag, Flyweight, Identity, Info, Item, Key, Method, Node, NullObject,
    Option, Proxy, Protocol, Peer, Query Record, Service, Strategy, Style,
    State, Target, Template ethod, Type, Unit
    

    View Slide

54. Sammlung Verben
    Sammlung Verben
    (nominalisiert)
    (nominalisiert)
    Adapter, Adjuster, Attacher, Binder, Builder, Calculator, Coordinator,
    Container, Converter, Controller, Connector, Collector, Configurer,
    Constructor, Composer, Commander, Creater, Debugger, Decorator,
    Decider, Designer, Delegator, Destroyer, Dispatcher, Dumper, Editor,
    Executor, Exporter, Extractor, Factory, Filter, Formatter, Generator,
    Initializer, Identifier, Interpreter, Inserter, Informer, Importer, Iterator,
    Listener, Limiter, Machine, Marker, Mediator, Memento, Matcher,
    Mapper, Messenger, Mover, Observer, Parser, Presenter, Provider,
    Preparer, Printer, Processor, Receiver, Reader, Recorder, Remover,
    Resolver, Sanitizer, Selector, Scheduler, Sender, Serializer, Sorter,
    Standardizer, Supporter, Synchronizer, Tokenizer, Tracer, Tracker,
    Validator, Viewer, Visitor, Writer
    

    View Slide

55. Word Association Lookup
    Word Association Lookup
    https://wordassociations.net/en
    

    View Slide

56. Synonyme
    Synonyme
    https://www.thesaurus.com/
    

    View Slide

57. Fazit
    Fazit
    

    View Slide

58. Sobald ich mit dem Namen zufrieden bin,
    bin ich gewöhnlich auch zufrieden mit dem Design.
    

    View Slide

59. Danke!
    Danke!
    

    View Slide

60. https://joind.in/talk/62eba
    

    View Slide

61. Fragen?
    Fragen?
    

    View Slide

62. Quellen
    Quellen
    Bild Höhlenkunst:
    Bild Binärcode:
    Assembler Gif:
    C code:
    Bild Rechtschreibprüfung:
    Wikimedia
    ELECTRÓNICA, INFORMÁTICA
    Sector Wars - a previously unrelease
    8-bit video game
    programiz.com
    PhpStorm Hilfe
    https://medium.com/coding-skills/clean-code-101-
    meaningful-names-and-functions-bf450456d90c
    https://de.wikipedia.org/wiki/Höhere_Programmiers
    

    View Slide