Handige naam functie/variabele/class?

[Rekcor]

Tijdens het programmeren kan het zomaar gebeuren dat je een variabele, een functie, of een class/object een naam moet geven. Nu zit ik daar altijd mee te worstelen, want wat is een handige naam? Dus: een naam die andere programmeurs een goed idee geeft over wat de functie/variabele/class/het object doet/voorstelt.

In dit topic zouden we voorstellen kunnen doen voor zulke namen, en elkaar feedback kunnen geven.

Bijv. ik wil nu een functie maken waarmee je in kunt stellen dat de properties van het object niet ge'set' kunnen worden door andere objecten (maar wel door functies van het object zelf).

Is: disablePublicInterface() wat? De property is dan: hasPublicInterface.

[Miyamoto]

Rekcor schreef op maandag 15 augustus 2011 @ 12:02:
wat is een handige naam?

Rekcor schreef op maandag 15 augustus 2011 @ 12:02:
Dus: een naam die andere programmeurs een goed idee geeft over wat de functie/variabele/class/het object doet/voorstelt.

Something like that?

Ik denk dat smaken ook deels persoonlijk zijn, zeker in bijzondere (?) gevallen als je nu als voorbeeld geeft. Voor de algemene namen zou je ook kunnen kijken naar bekende frameworks etc, hoe daar de namen worden gegeven.

[ Voor 0% gewijzigd door Miyamoto op 15-08-2011 12:09 . Reden: Typefout ]

[Gerco]

Het object zal nog steeds een public interface hebben, dat verander je niet door het object op slot te zetten. Je kan dit op een aantal manieren oplossen:

• Je ziet het als op slot zetten van het object en je noemt je method lockSetters() of setReadonly()/isReadonly().
• Je verandert je ontwerp en maakt een builder die een object teruggeeft met alleen getters
• Je maakt een method die een object teruggeeft wat een interface implementeerd zonder setters. Kan best hetzefde object zijn, maar zonder expliciete cast kun je dan niets meer veranderen.
• Je wrapt het in een Unmodifiable* wrapper (UnmodifiableList/Map/Set).

Er zijn nog wel wat andere mogelijkheden, maar deze kwamen nu even in me op.

[Verwijderd]

Heb ook wat inspiratie nodig, mijn onzinnige namen zonder comments zijn een beetje onoverzichtelijk/vergeten wat het doet en eerst code doorpluizen voordat ik er iets mee kan!(de namen van variables bij mij zijn meestal a,b,c,d,...,a1,b1,c1, enzovoort)

[Verwijderd]

Ik code altijd heel extreem verbose, van andere mensen die mijn code wel eens hebben gelezen hoor ik dan dat ze net zo goed een heel boeken hadden kunnen gaan lezen zoveel tekst was het. Maar sommigen mensen vinden het juist wel duidelijk. Met extreem verbose bedoel ik dan method namen als: DivideGivenNumberByFive ofzo.

[YopY]

Rekcor schreef op maandag 15 augustus 2011 @ 12:02:
Bijv. ik wil nu een functie maken waarmee je in kunt stellen dat de properties van het object niet ge'set' kunnen worden door andere objecten (maar wel door functies van het object zelf).

Terzijde, maar daar heb je in de meeste OO-talen een modifier voor, die heet 'private' . Een object op slot kunnen zetten (dwz de state van die modifiers aanpassen of hoe je het maar wilt noemen) klinkt als een code smell. Zou je hier iets over kunnen uitweiden?

[DEiE]

Verwijderd schreef op maandag 15 augustus 2011 @ 12:13:
Heb ook wat inspiratie nodig, mijn onzinnige namen zonder comments zijn een beetje onoverzichtelijk/vergeten wat het doet en eerst code doorpluizen voordat ik er iets mee kan!(de namen van variables bij mij zijn meestal a,b,c,d,...,a1,b1,c1, enzovoort)

Wat houdt je tegen om een betere naam te kiezen? Variabelen als a, b, c, etc. zijn zo'n beetje de slechtste die er zijn.
Wat je in je achterhoofd moet houden bij het verzinnen van de naam is, wat doet het? Dat moet je al een eind op weg helpen.

Een paper van http://www.objectmentor.com (zowieso wel een mooie site) over naamgevingen.

[Rekcor]

YopY schreef op maandag 15 augustus 2011 @ 12:29:
[...]


Terzijde, maar daar heb je in de meeste OO-talen een modifier voor, die heet 'private' . Een object op slot kunnen zetten (dwz de state van die modifiers aanpassen of hoe je het maar wilt noemen) klinkt als een code smell. Zou je hier iets over kunnen uitweiden?

Eigenlijk was dit niet de bedoeling van dit topic, maar goed: e.e.a. vind plaats in de browser, waarin twee Javascript-objecten gelinkt zijn aan twee DOM-objecten (div-jes). Als de gebruiker de ene div versleept, moet de andere daarop reageren. Versleept de gebruiker de andere div, dan moet de ene daar op reageren. Beide hebben dus een listener functie op de ander.

Het probleem ligt voor de hand: verplaats object 1, dan reageert object 2, waarnaar object 1 weer luistert, waarnaar object 2 weer luistert, etc.

Dus: op het moment dat de listener functies worden gedraaid, moet heb object tijdelijk even 'doof' zijn voor andere objecten.

[Woy]

Verwijderd schreef op maandag 15 augustus 2011 @ 12:28:
Ik code altijd heel extreem verbose, van andere mensen die mijn code wel eens hebben gelezen hoor ik dan dat ze net zo goed een heel boeken hadden kunnen gaan lezen zoveel tekst was het. Maar sommigen mensen vinden het juist wel duidelijk.

Ik heb ook liever duidelijk, maar lange variabele namen dan onduidelijk en korte namen

Met extreem verbose bedoel ik dan method namen als: DivideGivenNumberByFive ofzo.

Ik vind wel dat de verbositeit nog nut moet hebben. Sowieso vind ik het niet handig dat je een "Magic" number in je method name opneemt, want misschien verandert dat nog wel. Maar noem het dan gewoon DivideByFive, het "GivenNumber" voegt immers IMHO geen duidelijkheid toe.

[NMe]

Rekcor schreef op maandag 15 augustus 2011 @ 13:43:
[...]

Eigenlijk was dit niet de bedoeling van dit topic, maar goed: e.e.a. vind plaats in de browser, waarin twee Javascript-objecten gelinkt zijn aan twee DOM-objecten (div-jes). Als de gebruiker de ene div versleept, moet de andere daarop reageren. Versleept de gebruiker de andere div, dan moet de ene daar op reageren. Beide hebben dus een listener functie op de ander.

Het probleem ligt voor de hand: verplaats object 1, dan reageert object 2, waarnaar object 1 weer luistert, waarnaar object 2 weer luistert, etc.

Dus: op het moment dat de listener functies worden gedraaid, moet heb object tijdelijk even 'doof' zijn voor andere objecten.

Of je moet een derde observer-object maken dat het verplaatsen voor je regelt. Dat lijkt me een heel stuk cleaner dan je huidige insteek en lost meteen je probleem op.

[alex3305]

Je kunt in plaats van extreme verbose programmeren er ook voor kiezen om documentatie wat beter te doen binnen de code. Zo doe ik het persoonlijk altijd. Daarnaast wil ik nog weleens letters gebruiken als variabele namen. Iets wat ik mijzelf dan ook redelijk af moet leren .

Overigens vind ik het keyword this (of self of Classname) vaak ook ontzettend veel leesbaarheid toevoegen in de code. Je weet dan meteen waar je moet zoeken. Dit doe ik dan in combinatie met een leading underscore bij variabelen. Ook sorteer ik mijn klassen eigenlijk altijd op access modifier > alfabetische volgorde, dus als voorbeeld:

C#:

class Voorbeeld {

   public static string StatischeVariabele = "blaataap";

   public bool _simpeleBoolean = false;

   private string _privateVariabele = "geen blaataap";

   public Voorbeeld() { }

   public string PrivateVariabeleWordtPubliek { get; set; }

   public bool GetSimpeleBoolean() { }

   protected void SetSimpeleBoolean(bool value) { }

   private void doSomethingSomething() { }

En so on.. Waarbij statische methoden onderaan staan.

[TeeDee]

alex3305 schreef op maandag 15 augustus 2011 @ 14:10:
Je kunt in plaats van extreme verbose programmeren er ook voor kiezen om documentatie wat beter te doen binnen de code. Zo doe ik het persoonlijk altijd.

Vind je?

Als we het DivideGivenNumberByFive er eens bij pakken.
Jij doet het wat rustiger en aan maakt er van; DoSomething. Jouw opvolger zal bij de eerste de beste keer dat hij/zij dit tegenkomt de hele reutel (indien mogelijk) refactoren naar DivideNumberByFive. Vervolgens moet de documentatie weer aangepast worden en misschien nog gekker: iedereen op de hoogte brengen dat er een breaking change is.

Nee, dan kies ik liever voor de easy way out: gewoon zo duidelijk mogelijk zijn

Of men blijft aan modderen en vervolgens vraagt iedereen zich af waarom nu juist jouw code op thedailywtf.com is verschenen.

[ Voor 7% gewijzigd door TeeDee op 15-08-2011 14:30 ]

[NMe]

alex3305 schreef op maandag 15 augustus 2011 @ 14:10:
Overigens vind ik het keyword this (of self of Classname) vaak ook ontzettend veel leesbaarheid toevoegen in de code. Je weet dan meteen waar je moet zoeken. Dit doe ik dan in combinatie met een leading underscore bij variabelen.

Een fatsoenlijke IDE markeert class members sowieso anders dan lokale variabelen en sowieso brengt een beetje IDE je bij een control+click ook naar de definitie/declaratie van hetgeen je op klikt, dus dat is een beetje een non-issue.

Ook sorteer ik mijn klassen eigenlijk altijd op access modifier > alfabetische volgorde, dus als voorbeeld:

Hoewel ik dat in zekere mate ook doe vind ik het belangrijker om te sorteren op functionaliteit, dus methods die vergelijkbare dingen doen staan bij elkaar. Ook hier helpt een goeie IDE weer, want een goede IDE kan naast je editor een lijstje laten zien van alle members en methods van een class, en daar kun je zelf dan weer in sorteren zonder dat dat in de code terug hoeft te komen.

Oh, en een underscore voor een public member zou ik dus persoonlijk nooit doen.

[ Voor 3% gewijzigd door NMe op 15-08-2011 14:47 ]

[bindsa]

Verwijderd schreef op maandag 15 augustus 2011 @ 12:13:
Heb ook wat inspiratie nodig, mijn onzinnige namen zonder comments zijn een beetje onoverzichtelijk/vergeten wat het doet en eerst code doorpluizen voordat ik er iets mee kan!(de namen van variables bij mij zijn meestal a,b,c,d,...,a1,b1,c1, enzovoort)

Just plain silence

Ik doe zelf vaak alles camelCase,

Bij variabelen vermeldt ik het type (hangt wel een beetje van de taal af of dit zinvol is).

Klassenamen beginnen bij mij met een hoofdletter.

code:

intUserId;

getUsers()

class Users {
...
}

Bij databasevelden heb ik de eigenaarde gewoonte om alleen lowercase letters te gebruiken en _ als koppelteken te gebruiken, dus:

code:

last_modified
user_id
id

Bij methodes laat ik in de naam zien wat er globaal gebeurt, dus:

code:

getUsers()

i.p.v.:

code:

users()

Interne functies, functies die alleen door de klasse zelf gebruikt mogen worden geef ik vaak een _ prefix, dus:

code:

private function _getUsers() {

}

Als ik MVC programmeer geef ik met de bestanden aan wat voor type het is (uitzondering: controllers die in de URL worden aangeroepen), dus:

code:

users_view (view file)
users_model (model file)
users (controller die in URL wordt aangeroepen)

Uiteraard alles in het Engels.

[alex3305]

TeeDee schreef op maandag 15 augustus 2011 @ 14:29:
[...]

Vind je?

Als we het DivideGivenNumberByFive er eens bij pakken.
Jij doet het wat rustiger en aan maakt er van; DoSomething. Jouw opvolger zal bij de eerste de beste keer dat hij/zij dit tegenkomt de hele reutel (indien mogelijk) refactoren naar DivideNumberByFive. Vervolgens moet de documentatie weer aangepast worden en misschien nog gekker: iedereen op de hoogte brengen dat er een breaking change is.

[...]

Overdrijven is natuurlijk ook een vak. Tussen DivideGivenNumberByFive en DoSomething is natuurlijk hetzelfde verschil als A en Z. Gewoon twee uiterste dus. Zelf zou ik er dan DivideByFive of iets dergelijks van maken en dan in de documentatie het eventueel verduidelijken.

NMe schreef op maandag 15 augustus 2011 @ 14:46:
[...]

Een fatsoenlijke IDE markeert class members sowieso anders dan lokale variabelen en sowieso brengt een beetje IDE je bij een control+click ook naar de definitie/declaratie van hetgeen je op klikt, dus dat is een beetje een non-issue.

Deze discussie heb ik al eerder hier gevoerd en ik denk dat het vooral een kwestie van smaak is. Zelf gebruik of heb ik gebruik gemaakt van VS2008/VS2010, Eclipse en Netbeans en deze doen dit allemaal geloof ik goed. Echter probeer ik toch zoveel mogelijk self/this/Classname te gebruiken voor een member variabele voor mijn eigen leesbaarheid. Zelf vind ik gewoon dat de code er overzichtelijker van wordt.

Maar met programmeren is het uberhaupt belangrijk dat je consequent bent en dat het leesbaar blijft voor anderen. Vooral als je in een team werkt.

Hoewel ik dat in zekere mate ook doe vind ik het belangrijker om te sorteren op functionaliteit, dus methods die vergelijkbare dingen doen staan bij elkaar. Ook hier helpt een goeie IDE weer, want een goede IDE kan naast je editor een lijstje laten zien van alle members en methods van een class, en daar kun je zelf dan weer in sorteren zonder dat dat in de code terug hoeft te komen.

Oh, en een underscore voor een public member zou ik dus persoonlijk nooit doen.

Het was even een snel uitgetikt voorbeeld. Want public member variabelen zou ik uberhaupt niet gebruiken, maar in C# een property van maken of in een andere programmeertaal een getter/setter.

[ILUsion]

alex3305 schreef op maandag 15 augustus 2011 @ 14:10:
Je kunt in plaats van extreme verbose programmeren er ook voor kiezen om documentatie wat beter te doen binnen de code. Zo doe ik het persoonlijk altijd. Daarnaast wil ik nog weleens letters gebruiken als variabele namen. Iets wat ik mijzelf dan ook redelijk af moet leren .

Overigens vind ik het keyword this (of self of Classname) vaak ook ontzettend veel leesbaarheid toevoegen in de code. Je weet dan meteen waar je moet zoeken. Dit doe ik dan in combinatie met een leading underscore bij variabelen. Ook sorteer ik mijn klassen eigenlijk altijd op access modifier > alfabetische volgorde, dus als voorbeeld:

C#:

class Voorbeeld {

   public static string StatischeVariabele = "blaataap";

   public bool _simpeleBoolean = false;

   private string _privateVariabele = "geen blaataap";

   public Voorbeeld() { }

   public string PrivateVariabeleWordtPubliek { get; set; }

   public bool GetSimpeleBoolean() { }

   protected void SetSimpeleBoolean(bool value) { }

   private void doSomethingSomething() { }

En so on.. Waarbij statische methoden onderaan staan.

Commentaar in code is overrated. Als je je code verbose schrijft, kan je in veel gevallen zonder commentaar (niet altijd natuurlijk), maar voor mij is dat een mooi streefdoel: zo weinig mogelijk commentaar in de code (ik tel javadoc, MATLAB cell mode, ... niet als echte commentaar). Commentaar en code worden immers niet automatisch gelijkgehouden, dus je kan wel een samenvatting geven in je commentaar; maar uiteindelijk kan je enkel vertrouwen op wat er in de code staat. Niets zo erg als commentaar die A zegt en code die B doet.

Met enkele letters als variabelen is er ook niets mis in mijn ogen, zolang het consistent is en de lengte van je variabele evenredig is met de scope waarbinnen je hem gebruikt. Een iterator "i" is in mijn ogen dus geen probleem (een iterator "iteratorWhichIteratesOverAGivenNumberRange" of iets dergelijks is overkill), vermits je die toch maar enkele lijnen gebruikt en waarschijnlijk heel vaak gebruikt.

Als ik zelf code schrijf en itereer over een set van objecten, statements, ... kort ik dat vaak af naar enkele letters of een enkele letter:

code:

// Java
for (Statement stat: statements){ ... }
for (Type T: types){ ... } // overblijfsel van mijn Pascal-dagen, denk ik

%MATLAB
for obj = objects
  ...
end

Binnen een grotere scope, gebruik ik meer guidelines (taal-afhankelijk dus), dus gewoon voluit schrijven wat er in de variabele zit of je houden aan bepaalde conventies daaromtrent. In MATLAB zou ik een variabele die het aantal auto's bevat 'nCars' noemen (en een iteratievariabele 'iCar', 'jCar', ... afhankelijk van de context of zelfs gewoon 'i' of 'j' als je die indices heel erg veel nodig hebt).

Ik hou mij ook zo veel mogelijk aan puur Engelstalige code, leest makkelijker weg dan half-om-half.

[TeeDee]

alex3305 schreef op maandag 15 augustus 2011 @ 15:08:
[...]

Overdrijven is natuurlijk ook een vak. Tussen DivideGivenNumberByFive en DoSomething is natuurlijk hetzelfde verschil als A en Z. Gewoon twee uiterste dus. Zelf zou ik er dan DivideByFive of iets dergelijks van maken en dan in de documentatie het eventueel verduidelijken.

Ik zal 't voortaan bijzetten dat ik wat aan het overdrijven was.
Punt is: je noemt 't nu al DivideByFive waardoor je imo de documentatie niet meer aan hoeft te passen
Tenzij we natuurlijk in de code feitelijk een DivideBySix doen De method name is sowieso slecht dsu.

Waar ik eigenlijk gewoon op ageer is: ach, ik neem iets minder zinnige methodnames en corrigeer dit wel met documentatie.

[Janoz]

T.H. Lassche schreef op maandag 15 augustus 2011 @ 15:00:
Uiteraard alles in het Engels.

Ah, gaan we die discussie hier nu ook weer houden? Of zullen we even een korte shortcut nemen en alvast tot de conclusie komen dat je het beste voor je domein gewoon de taal moet nemen welke ook in het probleem domein gebruikt wordt.

[alex3305]

TeeDee schreef op maandag 15 augustus 2011 @ 15:12:
[...]

Waar ik eigenlijk gewoon op ageer is: ach, ik neem iets minder zinnige methodnames en corrigeer dit wel met documentatie.

Ik snap je punt wel. Echter ben ik wel van mening dat ontzettend lange methodenamen ook tot onleesbaarheid kunnen zorgen. Als je dan een methodenaam wat korter kunt houden en daarbij door goede documentatie het toch duidelijk kunt maken, het voor mij ook goed werkt.

[NMe]

alex3305 schreef op maandag 15 augustus 2011 @ 15:14:
[...]

Ik snap je punt wel. Echter ben ik wel van mening dat ontzettend lange methodenamen ook tot onleesbaarheid kunnen zorgen. Als je dan een methodenaam wat korter kunt houden en daarbij door goede documentatie het toch duidelijk kunt maken, het voor mij ook goed werkt.

Een goede methodnaam heeft voor mij een hele simpele definitie. Omschrijf in zo weinig mogelijk letters zo goed mogelijk wat het resultaat is van het aanroepen van die method. Een method als getUserById(int id) lijkt me prima zonder verder commentaar. Vervolgens kun je je in het commentaar beperken tot het hoe en waarom van je code, in plaats van dat je ook nog moet uitleggen wát je method doet.

[Janoz]

alex3305 schreef op maandag 15 augustus 2011 @ 15:14:
Ik snap je punt wel. Echter ben ik wel van mening dat ontzettend lange methodenamen ook tot onleesbaarheid kunnen zorgen. Als je dan een methodenaam wat korter kunt houden en daarbij door goede documentatie het toch duidelijk kunt maken, het voor mij ook goed werkt.

Zelfs al gebruik je een fatsoenlijke IDE, dan nog heb je een handeling nodig om die documentatie te kunnen zien (al was het maar een hoover van de muis). Methode naam korter maken kan ik me in vinden, maar wanneer dat betekend dat je extra documentatie nodig hebt om het te omschrijven dan maak je hem imho te kort. Documentatie is imho meer bedoeld voor pre- en postcondities.

[Verwijderd]

volgens mij is de 'regel' bij meeste talen / frameworks dat een naam beschijvend moet zijn, hoeft dus niet echt een hele zin te zijn maar iets van 3 letters is meestal te weinig.

verder heb ik zelf de regels :
functienamen camelcased, beginnend met een lowercase ; dus getName ipv GetName ... protected / private methods beginnen met een _

variables : beginnen met een type identifier (voor non strict talen), vind ik zelf fijn werken, dus een array begint met een 'a' : $aNames , objecten met een o : $oUser , booleans met een b : $bIsChanged etc etc

ook hier geldt dat private en protected met een _ beginnen.

classnames altijf met hoofdletter beginnend : class User , class WeirdShit

Verder ben ik ook gewoon voor engelse code ... is voorkeur (dus geen aanleiding om die cow weer out of the ditch te halen) , ook omdat bij vele bedrijven waar ik gewerkt heb er wel een of twee niet-nederlanders zaten.

[Cartman!]

Verwijderd schreef op maandag 15 augustus 2011 @ 16:22:
variables : beginnen met een type identifier (voor non strict talen), vind ik zelf fijn werken, dus een array begint met een 'a' : $aNames , objecten met een o : $oUser , booleans met een b : $bIsChanged etc etc

Als je dat nodig hebt dan is je documentatie niet in orde en/of je functies zijn te lang

[Janoz]

Verwijderd schreef op maandag 15 augustus 2011 @ 16:22:
Verder ben ik ook gewoon voor engelse code ... is voorkeur (dus geen aanleiding om die cow weer out of the ditch te halen) , ook omdat bij vele bedrijven waar ik gewerkt heb er wel een of twee niet-nederlanders zaten.

Haalt koe toch uit sloot omdat je het blijkbaar niet eens bent over de shortcut

Voor die net nederlanders maakt het toch geen reet uit of de zelfstandige naamwoorden in het nederlands, engels of swahili zijn? Wanneer er in codevoorbeelden Foo of Bar gerbuikt wordt, is de code toch ook niet ineens niet te begrijpen geworden?

[ Voor 7% gewijzigd door Janoz op 15-08-2011 16:55 ]

[NMe]

Janoz schreef op maandag 15 augustus 2011 @ 16:54:
[...]

Haalt koe toch uit sloot omdat je het blijkbaar niet eens bent over de shortcut

Voor die net nederlanders maakt het toch geen reet uit of de zelfstandige naamwoorden in het nederlands, engels of swahili zijn? Wanneer er in codevoorbeelden Foo of Bar gerbuikt wordt, is de code toch ook niet ineens niet te begrijpen geworden?

Dan kun je net zo goed meteen je variabelen a, b, c, enz. noemen. Natuurlijk maakt het wel uit in welke taal je variabele benoemd is. Als de programmeur dat niet kan begrijpen dan moet er ineens veel meer verboos commentaar opgenomen worden. En uitgerekend bij programmeurs die niet graag in het Engels coden is dat commentaar vaak ver te zoeken.

[Janoz]

Ik zeg niet dat je willekeurige namen moet nemen. Wat ik zeg is dat het voor het begrip van de code niet uitmaakt of je getBike(), getFiets() of getBaiskeli() gebruikt. Als je vervolgens bij een klant zit die zijn complete bedrijfsdomein in het nederlands heeft, dan kun je natuurlijk voor elk van die termen een engels woord gaan verzinnen, maar ik kan je verzekeren dat dat er voor zorgt dat je meer moet documenteren (en eventueel flink refactoren wanneer er op 2 momenten toevallig een andere vertaling gekozen is).

De variabele namen a,b en c zijn bijvoorbeeld heel valide, wanneer je een methode aan het schrijven bent die het aantal nulpunten van een parabool moet berekenen.^*

[NMe]

Janoz schreef op maandag 15 augustus 2011 @ 20:59:
Ik zeg niet dat je willekeurige namen moet nemen. Wat ik zeg is dat het voor het begrip van de code niet uitmaakt of je getBike(), getFiets() of getBaiskeli() gebruikt.

Dat maakt wel degelijk uit. Ik zou een baiskeli niet thuis kunnen brengen en zou als ik die code lees daadwerkelijk ofwel naar de uitvoer moeten kijken ofwel naar de method zelf om te zien wát ik nu eigenlijk ophaal, als ik die code zou moeten onderhouden/debuggen. Ik zal niet zeggen dat je het sowieso niet moet doen, maar er is in onze branche toch echt wel een sterke voorkeur voor Engels, en terecht IMO.

[Nick_S]

Je zou eens kunnen kijken naar Episode 2 Names++ van Uncle Bob of het gelijknamige hoofdstuk uit Clean Code lezen.

[ Voor 3% gewijzigd door Nick_S op 15-08-2011 21:45 ]

[H!GHGuY]

Ik hou het ook liever verbose. Wat ik ook veel zie is dat naamgeving vanuit het perspectief van de klasse gedaan wordt en niet vanuit het perspectief van de gebruiker.

code:

class NTPClock
{
   void UpdateTimeFromNTPServer();
   // in plaats van het betere
   void SynchronizeTime();
}

Gebruikers hoeven de implementatie helemaal niet te kennen, ze willen enkel weten wat het effect is op het desbetreffende object.

Wie me de redenen kan opsommen waarom namen beginnend met "Check..." altijd slecht zijn krijgt een virtuele lolly.

spoiler:

1) het zegt niet wat er gebeurt als de check lukt (als er al iets gebeurt)
2) het zegt niet wat er gebeurt als de check faalt (als er al iets gebeurt)
3) meestal is de return code dan nog een boolean/status code en is het dus ook niet duidelijk of die nou aangeeft dat de check gelukt is of gefaald.

[Niemand_Anders]

Functies welke bij ons een boolean waarde terug geven moeten volgens onze coding standards altijd beginnen met 'IsXX'. Dus een functie welke een email adres controleert zal de naam IsValidEmail() krijgen. Overigens houden wij code altijd engeltalig ongeacht het probleem domein. Een uitzondering is als een vertaling van Nederland naar Engels onduidelijk wordt.

Consistente code tussen programmeurs is goud waard, ook al zijn de codings standaards nog zo stom..

[Janoz]

NMe schreef op maandag 15 augustus 2011 @ 21:21:
[...]

Dat maakt wel degelijk uit. Ik zou een baiskeli niet thuis kunnen brengen en zou als ik die code lees daadwerkelijk ofwel naar de uitvoer moeten kijken ofwel naar de method zelf om te zien wát ik nu eigenlijk ophaal, als ik die code zou moeten onderhouden/debuggen. Ik zal niet zeggen dat je het sowieso niet moet doen, maar er is in onze branche toch echt wel een sterke voorkeur voor Engels, en terecht IMO.

Als je software aan het maken bent waarbij de hele business het over een baiskeli heeft. Bugmeldingen binnenkomen waarbij gebruikers melden dat er niet de juiste baiskeli opgehaald wordt. Feature requests praten over het weergeven van baiskeli opties, dan kun je in je code maar beter ook gaan praten over een baiskeli.

En dan heb ik het nog niet eens over de terminologie waarvoor eigenlijk geen fatsoenlijke engelse vertaling is.

[Janoz]

Niemand_Anders schreef op maandag 15 augustus 2011 @ 23:58:
...Een uitzondering is als een vertaling van Nederland naar Engels onduidelijk wordt.

Maar wie bepaalt die grens? Wat voor de één misschien nog duidelijk is, is voor de ander een stuk minder duidelijk. Daarnaast is het domein precies dat stukje van het probleem dat je aan het oplossen bent waarvoor geldt dat de klant er meer verstand van heeft (of iig zou moeten hebben) dan de ontwikkelaar.

Maar goed, even een linkje naar een post van mij in een vorige keer dat deze discussie gevoerd werd: Janoz in "[alg] Slechtste programmeervoorbeelden d..."

[Remus]

Verwijderd schreef op maandag 15 augustus 2011 @ 16:22:

verder heb ik zelf de regels :
functienamen camelcased, beginnend met een lowercase ; dus getName ipv GetName ... protected / private methods beginnen met een _

...

ook hier geldt dat private en protected met een _ beginnen.

Waarom zou je het jezelf moeilijk maken en private of protected methods en members prefixen met een underscore? Het voegt niks toe aan de informatie die je IDE je al biedt. Ik denk ook dat het hindert bij het programmeren: de method die oorspronkelijk public was, blijkt toch beter protected of private te zijn (of andersom), dan moet je dus naast de access modifier ook nog eens de naam gaan wijzigen (soms zelfs in meerdere classes), of je zit met een method die niet meer aan je regeltjes voldoet met verwarring etc tot gevolg omdat mensen op de naamgeving gaan vertrouwen ipv de hints van de IDE.

[Verwijderd]

Alstublieft

[Grijze Vos]

Janoz schreef op dinsdag 16 augustus 2011 @ 09:57:
[...]

Maar goed, even een linkje naar een post van mij in een vorige keer dat deze discussie gevoerd werd: Janoz in "[alg] Slechtste programmeervoorbeelden d..."

Ik ben op dat punt ondertussen om en het met je eens. Kwam zelf wel een interessante use case tegen in een project waar ik nu aan werk. Wat als je een probleemdomein hebt in het nederlands, met de potentie dat het product uiteindelijk ook in engeland afgezet gaat worden? In de software die ik nu georven heb is alles vertaald naar het engels, maar dat geeft een aantal onduidelijke vertalingen (gaat om bioscopen), bijvoorbeeld:

Zaal -> Theatre

Terwijl een "Theatre" net zo goed de hele bioscoop zou kunnen zijn.

[RayNbow]

Remus schreef op dinsdag 16 augustus 2011 @ 10:19:
[...]


Waarom zou je het jezelf moeilijk maken en private of protected methods en members prefixen met een underscore? Het voegt niks toe aan de informatie die je IDE je al biedt. Ik denk ook dat het hindert bij het programmeren: de method die oorspronkelijk public was, blijkt toch beter protected of private te zijn (of andersom), dan moet je dus naast de access modifier ook nog eens de naam gaan wijzigen (soms zelfs in meerdere classes), of je zit met een method die niet meer aan je regeltjes voldoet met verwarring etc tot gevolg omdat mensen op de naamgeving gaan vertrouwen ipv de hints van de IDE.

Als je toch al een IDE hebt, dan kan die voor jou alle namen wijzigen.

[NMe]

Grijze Vos schreef op dinsdag 16 augustus 2011 @ 10:47:
[...]

Ik ben op dat punt ondertussen om en het met je eens. Kwam zelf wel een interessante use case tegen in een project waar ik nu aan werk. Wat als je een probleemdomein hebt in het nederlands, met de potentie dat het product uiteindelijk ook in engeland afgezet gaat worden? In de software die ik nu georven heb is alles vertaald naar het engels, maar dat geeft een aantal onduidelijke vertalingen (gaat om bioscopen), bijvoorbeeld:

Zaal -> Theatre

Terwijl een "Theatre" net zo goed de hele bioscoop zou kunnen zijn.

Die vertaling heb je dan toch ook in je software zelf nodig? Waarom zou het daar wel duidelijk zijn en in je code niet?

Ik heb een vergelijkbaar probleem gehad met een virtuele caddy-app waar ik aan gewerkt heb. Een golfclub kan zowel de stok zijn waar je mee mept als de locatie waar je op speelt. Uiteindelijk heb ik dat verschil in de code duidelijk gemaakt door voor allebei de termen iets anders te verzinnen. Ik heb nu GolfEquipment en GolfCourse.

[Janoz]

Mijn punt is meer dat je, wanneer je een voor een nederlandse golfclub een registratie applicatie maakt, je niet moet gaan proberen om de player property 'hasGVB' naar iets anders te gaan vertalen. Ja, je kunt het engels maken, maar niemand begrijpt meer wat je eigenlijk met hasGSP bedoelt.

[CodeCaster]

NMe schreef op dinsdag 16 augustus 2011 @ 11:04:
[...]

Die vertaling heb je dan toch ook in je software zelf nodig? Waarom zou het daar wel duidelijk zijn en in je code niet?

Grijze Vos schreef op dinsdag 16 augustus 2011 @ 10:47:
potentie dat het product uiteindelijk ook in engeland afgezet gaat worden

Kortom, voorlopig enkel in Nederland, en de Nederlands sprekende opdrachtgever gaat het bij diverse vormen van communicatie (speccen, ontwerpen, testen) ook gewoon bij de Nederlandse termen houden.

In je hoofd, in je code en/of in je documentatie moet je dan steeds de vertaalslag van Zaal naar Theatre maken, alleen omdat je code in het Engels moet zijn omdat de app (specifiek: de GUI, relatief los van de code nota bene) eventueel in de toekomst vertaald moet gaan worden? YAGNI...

[Remus]

RayNbow schreef op dinsdag 16 augustus 2011 @ 10:57:
[...]

Als je toch al een IDE hebt, dan kan die voor jou alle namen wijzigen.

Dat vergt nog steeds een handeling die je kan overslaan, en dan zit je met een inconsistentie in de semantiek van je naamgeving... Doe dergelijke Hungarian-achtige notations gewoon niet en dan heb je dat probleem ook niet.

Daarnaast als ik iets van bijvoorbeeld public naar protected wijzig, en ik dien vanwege dit soort naamgevingregels ook de naam te veranderen, dan verander ik misschien ook nog eens tig andere sourcefiles terwijl dat niet echt noodzakelijk is voor de betreffende change.

[NMe]

Janoz schreef op dinsdag 16 augustus 2011 @ 11:43:
Mijn punt is meer dat je, wanneer je een voor een nederlandse golfclub een registratie applicatie maakt, je niet moet gaan proberen om de player property 'hasGVB' naar iets anders te gaan vertalen. Ja, je kunt het engels maken, maar niemand begrijpt meer wat je eigenlijk met hasGSP bedoelt.

Maar in het geval van een GVB is dat ook te begrijpen omdat dat AFAIK een bewijs van vaardigheid is dat anders is dan in andere landen. Toch schrijf ik dan in mijn code hasGVB en niet heeftGVB en noem ik een club nog steeds equipment danwel course en mijn baan heet een hole. Sporadisch een Nederlands woordje omdat er geen geschikte vertaling bestaat vind ik best. Maar doe het niet voor simpele dingen. Dat een garage een probleemdomein heeft dat om auto's draait en hij niet van plan is buitenlandse fillialen te openen wil nog niet zeggen dat mijn code het moet hebben over auto's.

CodeCaster schreef op dinsdag 16 augustus 2011 @ 11:46:
[...]

In je hoofd, in je code en/of in je documentatie moet je dan steeds de vertaalslag van Zaal naar Theatre maken, alleen omdat je code in het Engels moet zijn omdat de app (specifiek: de GUI, relatief los van de code nota bene) eventueel in de toekomst vertaald moet gaan worden? YAGNI...

Nee, omdat die code later nog onderhouden moet worden en jij geen enkele garantie hebt dat jij dat bent. Wij hebben sinds ruim 2 jaar een Poolse dame als developer en toen zij begon was iedereen maar wat blij dat alles wat wij op kantoor doen van code tot documentatie allemaal in het Engels is. En dan heb ik het nog niet eens over outsourcing.

[CodeCaster]

Dat zijn een hoop voorwaarden. Als je als bedrijf niet aan outsourcing doet en geen plannen hebt op dat gebied voor de komende jaren, als al je medewerkers gewoon Nederlands spreken, de communicatie met de opdrachtgever gaat in het Nederlands èn het domein barst van de lastig vertaalbare termen, dan is het mijns inziens prima verdedigbaar om voor dat project gebruik te maken van Nederlandstalige klassen, variabelen, tabellen en dergelijke.

Begrijp me niet verkeerd, ik prefereer ook te programmeren in het Engels, maar het gaat gewoon niet in alle gevallen op.

Eigenlijk dit dus:

NMe schreef op dinsdag 16 augustus 2011 @ 12:55:
Sporadisch een Nederlands woordje omdat er geen geschikte vertaling bestaat vind ik best. Maar doe het niet voor simpele dingen.

Maar dan niet door elkaar in één project alsjeblieft...

[ Voor 26% gewijzigd door CodeCaster op 16-08-2011 13:05 ]

[Sardaukar]

Alles in het Engels is leuk, maar je hebt ook opdrachten waarin de vertaling naar het Engels heel lastig wordt. Ik heb op een blauwe maandag software geschreven voor loonberekeningen en daarin zaten termen als:

• Loonheffingsloon
• Heffingskorting
• DGA (Directeur Groot Aandeelhouder)
• Percentage Bijzonder Tarief
• Garantieloon

Heel leuk als je zelf in eerste instantie weinig ervaring met de materie hebt. We hebben dus ook heel snel de afspraak gemaakt om deze termen in ons model Nederlandstalig te houden. Op die manier was het een stuk makkelijker bespreekbaar met onze klanten en materie-deskundigen.

[Janoz]

NMe schreef op dinsdag 16 augustus 2011 @ 12:55:
Maar in het geval van een GVB is dat ook te begrijpen omdat dat AFAIK een bewijs van vaardigheid is dat anders is dan in andere landen. Toch schrijf ik dan in mijn code hasGVB en niet heeftGVB en noem ik een club nog steeds equipment danwel course en mijn baan heet een hole.

Ik heb het ook alleen over domein. Uiteraard ga je de rest niet vertalen. Dat is immers 'je eigen domein'. Pattern namen, standaard algoritmen, documentatie, heck, zelfs de vervoegingen van domein objecten hou je uiteraard in het Engels.

Sporadisch een Nederlands woordje omdat er geen geschikte vertaling bestaat vind ik best. Maar doe het niet voor simpele dingen. Dat een garage een probleemdomein heeft dat om auto's draait en hij niet van plan is buitenlandse fillialen te openen wil nog niet zeggen dat mijn code het moet hebben over auto's.

Waarom niet? Waarom de extra vertaalslag inbouwen? Als de gebruiker of de klant het over de burg heeft, waarom moet je dan nog een extra na gaan denken welke vertaling je daar ooit voor bedacht hebt? En wie zegt dat twee ontwikkelaars die de NL term tegenkomen allebij dezelfde engelse term gaan pakken?

Bij een garage lijkt het misschien nog simpel, maar grotere bedrijven hebben vaak een compleet alleen intern echt bekende terminologie. Wie ben jij om te zeggen dat de terminologie die daar vaak al decenia gebruikt wordt maar eens even helemaal op de schop zou moeten? Heck, de kans is best aanwezig dat je in eerste instantie niet eens weet wat de nederlandse term uberhaupt inhoudt. Vertaal je die term vervolgens en kom je een half jaar later die code weer eens tegen dan is de kans aanwezig dat je geen idee meer hebt waar het over ging, en aangezien niemand de door jezelf verzonnen terminologie gebruikt kan niemand anders vertellen wat het eigenlijk inhoud. En nee, dit is niet hypothetisch. Dit heb ik al enkele keren in grote projecten meegemaakt.

Als je je eigen klant/product owner bent maakt het natuurlijk niet uit, maar in alle andere gevallen: Neem de terminologie over van je klant/productowner.

[NMe]

CodeCaster schreef op dinsdag 16 augustus 2011 @ 13:03:
Dat zijn een hoop voorwaarden. Als je als bedrijf niet aan outsourcing doet en geen plannen hebt op dat gebied voor de komende jaren, als al je medewerkers gewoon Nederlands spreken, de communicatie met de opdrachtgever gaat in het Nederlands èn het domein barst van de lastig vertaalbare termen, dan is het mijns inziens prima verdedigbaar om voor dat project gebruik te maken van Nederlandstalige klassen, variabelen, tabellen en dergelijke.

Mijn baas had ook nooit de intentie om een Engelssprekende werknemer aan te nemen maar hij was er wel op voorbereid toen het toch gebeurde. Sommige dingen kun je niet plannen terwijl het een kleine moeite is om er klaar voor te zijn.

Eigenlijk dit dus:

[...]

Maar dan niet door elkaar in één project alsjeblieft...

Waarom niet? Als je eigen standaard voorschrijft dat je in het Engels programmeert en je dat voor 99% van het project ook kan doen maar voor die ene specialistische uitdrukking een Nederlandse term nodig hebt (voorbeelden te over een paar posts hierboven), waarom dan niet? Heffingskorting is zo'n typisch Nederlandse term die waarschijnlijk in het buitenland niet eens relevant is. Tegelijkertijd moet de rest van de code best Engels kunnen zijn, niet in de laatste plaats omdat Engels als taal veel minder verbose is dan Nederlands.

Janoz schreef op dinsdag 16 augustus 2011 @ 13:09:
[...]

Ik heb het ook alleen over domein. Uiteraard ga je de rest niet vertalen. Dat is immers 'je eigen domein'. Pattern namen, standaard algoritmen, documentatie, heck, zelfs de vervoegingen van domein objecten hou je uiteraard in het Engels.

Mooi, zijn we het daar in elk geval over eens.

Waarom niet? Waarom de extra vertaalslag inbouwen? Als de gebruiker of de klant het over de burg heeft, waarom moet je dan nog een extra na gaan denken welke vertaling je daar ooit voor bedacht hebt? En wie zegt dat twee ontwikkelaars die de NL term tegenkomen allebij dezelfde engelse term gaan pakken?

Bij een garage lijkt het misschien nog simpel, maar grotere bedrijven hebben vaak een compleet alleen intern echt bekende terminologie. Wie ben jij om te zeggen dat de terminologie die daar vaak al decenia gebruikt wordt maar eens even helemaal op de schop zou moeten? Heck, de kans is best aanwezig dat je in eerste instantie niet eens weet wat de nederlandse term uberhaupt inhoudt. Vertaal je die term vervolgens en kom je een half jaar later die code weer eens tegen dan is de kans aanwezig dat je geen idee meer hebt waar het over ging, en aangezien niemand de door jezelf verzonnen terminologie gebruikt kan niemand anders vertellen wat het eigenlijk inhoud. En nee, dit is niet hypothetisch. Dit heb ik al enkele keren in grote projecten meegemaakt.

Als je je eigen klant/product owner bent maakt het natuurlijk niet uit, maar in alle andere gevallen: Neem de terminologie over van je klant/productowner.

Ik mis hier eigenlijk vooral de invloed van commentaar. Elke class hoort wat mij betreft een stukje commentaar te hebben dat uitlegt waar de class voor staat en eventueel wat je ermee kan doen. Elke method hoort ook een dergelijk stukje commentaar te hebben. Uiteindelijk maakt het door dat commentaar niet uit of je een functie "getBike", "getFiets", "aap" of "functie684" noemt. Het verschil is dat een getBike door elke programmeur die door code heen bladert wel te begrijpen is zonder de class/methoddefinitie erbij te pakken, ongeacht afkomst. Is er onverhoopt toch nog iets niet helemaal duidelijk dan is dat commentaar er als fallback. In de situatie die jij omschrijft heb je als programmeur mogelijk dat commentaar altijd nodig en dat haalt je helemaal uit je flow. Mij wel in elk geval.

[Sardaukar]

NMe schreef op dinsdag 16 augustus 2011 @ 13:35:
[...]
Ik mis hier eigenlijk vooral de invloed van commentaar. Elke class hoort wat mij betreft een stukje commentaar te hebben dat uitlegt waar de class voor staat en eventueel wat je ermee kan doen. Elke method hoort ook een dergelijk stukje commentaar te hebben. Uiteindelijk maakt het door dat commentaar niet uit of je een functie "getBike", "getFiets", "aap" of "functie684" noemt. Het verschil is dat een getBike door elke programmeur die door code heen bladert wel te begrijpen is zonder de class/methoddefinitie erbij te pakken, ongeacht afkomst. Is er onverhoopt toch nog iets niet helemaal duidelijk dan is dat commentaar er als fallback. In de situatie die jij omschrijft heb je als programmeur mogelijk dat commentaar altijd nodig en dat haalt je helemaal uit je flow. Mij wel in elk geval.

Een probleem met commentaar is dat deze nog wel eens uit de pas gaat lopen met de daadwerkelijke code. Ik heb dan liever verbose, self-describing code dan terse code met commentaar wat niet geheel de lading dekt.

[Janoz]

NMe schreef op dinsdag 16 augustus 2011 @ 13:35:
...

De denkfout die je blijft maken is dat je er vanuit gaat dat je probleem domein simpel genoeg is dat het voor iedereen instantaan te begrijpen is. Dat is voor fiets zo, maar wat als die buitenlandse werknemer uberhaupt nog nooit een fiets gezien heeft? Als de termen lastiger worden dan maakt het toch eigenlijk helemaal niet meer uit of je het ding een Ding, Foo of Bar noemt? Zolang je het overal maar een Ding, Foo of Bar noemt. En als de klant nu precies dezelfde term gebruikt.... Zeker bij de wat grotere projecten is heb je heel specifieke terminologie. Je zegt dat slechts 1% van de terminologie misschien niet te vertalen is, maar dat percentage licht een flink stuk hoger. Daarnaast is het natuurlijk onzin dat het je uit de flow haalt. Het gaat over een iets en dat iets heeft een naam. Die naam wordt door iedereen gebruikt. Dat die naam dan toevallig in het Nederlands is is helemaal niet meer relevant.

Pak voor de grap gewoon eens het laatste dekkings overzicht van je verzekering erbij en probeer dit eens helemaal te vertalen naar het engels. Je zult zien dat dat af en toe nog wel lastig is en zeker niet instantaan is. Waarom zou je het jezelf dan moelijk gaan maken? Een methode calculateDekkingsGraad geeft keurig aan dat je het gegeven 'dekkingsgraad' gaat berekenen. En als je bij je klant vraag hoe je de dekkingsgraad eigenlijk moet berekenen weet hij precies waar je het over hebt en voor de indier maakt het ook niet uit of je het nu over DekkingsGraad of CoverageDegree hebt.

[NMe]

Ik ben toevallig met een site bezig die veel met juridische termen bezig is. Een advocaat noem ik daar toch echt intern gewoon "lawyer" terwijl ik de echt specifieke, onvertaalbare dingen wel op zijn Nederlands hou. Noem het een kwestie van smaak maar ik vind het smerig om te veel Nederlands in mijn verder Engelstalige code op te nemen.

[Janoz]

Waarom advocaat en (bv) zaak wel, maar grifier en arrondissement niet? Ontwikkelaars zijn over het algemeen toch altijd wat eigenwijs. "Ja, ik weet dat jullie het al eeuwen zo doen, maar ik doe het toch anders". Over een paar jaar vraag ik het je nog wel een keer om te kijken hoe je er dan tegenaan kijkt .

[MSalters]

Ik heb het plezier gehad om aan financiele code te werken van een Frans bedrijf. Die hebben eerst een maand mogen besteden aan het refactoren van hun code naar het Engels. Dat hebben ze toch maar gedaan, want het alternatief was dat ze zelf de UI moesten bouwen. Daar waren ze als economen niet zo goed in.

Terug on topic: de property is een redelijk harde schending van het LSP.

[Remus]

NMe schreef op dinsdag 16 augustus 2011 @ 14:53:
Ik ben toevallig met een site bezig die veel met juridische termen bezig is. Een advocaat noem ik daar toch echt intern gewoon "lawyer" terwijl ik de echt specifieke, onvertaalbare dingen wel op zijn Nederlands hou. Noem het een kwestie van smaak maar ik vind het smerig om te veel Nederlands in mijn verder Engelstalige code op te nemen.

Naar mijn mening is dat een slechte vertaling. Afhankelijk van het land kan 'lawyer' namelijk ook jurist of 'iemand met een achtergrond in recht' (waaronder advocaten en juristen, maar ook rechters) betekenen, en waarom lawyer en niet bijvoorbeeld barrister, counsel, attorney, solicitor of advocate?