ander woord
Ik heb op mijn server een mapje waarin alle "code" van de website staat. Simpel gezegd is dat alle php en html code (eigenlijk alles behalve media-bestanden). Dat mapje heet op dit moment "private" omdat het buiten de document root staat en dus onbereikbaar is via de browser.
Echter, ik vind "private" eigenlijk niet zo'n goede naam meer. Immers, alles wat op de server staat en niet bereikbaar is via de browser is in principe 'private'. Een beetje nietszeggend dus.
Ik wil de naam dus wijzigen in een naam die aangeeft dat in die map alle code staat. De naam "code" vind ik dan weer te algemeen. Ik zit aan iets te denken als 'app' of 'program', maar iets zegt me dat er nog een betere naam is ... alleen ik kan er dus ff niet opkomen. Grr...
De naam moet aangeven dat in die map de "intelligentie", "besturing" of "workflow" van de website staat ... iets in die richting. Het moet niet te algemeen en vaag zijn (zoals bijv. 'core') en het moet ook kort zijn. App en program zou kunnen, maar zijn er wellicht nog betere opties?
Gewijzigd op 12/07/2016 22:54:13 door - Ariën -
Gewijzigd op 12/07/2016 23:02:28 door Ozzie PHP
maar is ook zo 'algemeen' en 'groots'
staat wel voor alles waar je op bouwt :) wat eigenlijk weer voor de basis staat ook
en dus niet je hele applicatie
snap de vraag ook niet zo goed, sorry :)
Gewijzigd op 12/07/2016 23:15:05 door Dennis WhoCares
Je hebt een website, en een aparte map (buiten de document root) waarin je alle php-bestanden en html-bestanden zet. Voor die map zoek ik een mooie naam.
Het is als het ware het "brein" of "de intelligentie" van de website. Normaal heet die map dus 'private' maar ik zoek een betere omschrijving.
lib?
library?
core?
EDIT
inc?
includes?
ik maak in mijn frameworkje onderscheid tussen de core (die in een library (sub)map staat) en application: custom code voor een specifieke website die voortborduurt op de core en deze kan overriden.
Gewijzigd op 12/07/2016 23:41:14 door Thomas van den Heuvel
Die mapnaam moet dus als het ware aangeven welk onderdeel van de website het is. Als ik die map zou verwijderen dan verwijder je het ??? van de website.
Toevoeging op 12/07/2016 23:45:08:
>> ik maak in mijn frameworkje onderscheid ...
Dat zie je inderdaad vaker ... app(lication) zou een optie kunnen zijn, maar ik heb het gevoel dat ik iets mis :-s
Bij veel projecten op GitHub wordt /src/ van source code gebruikt.
Wat me nog opvalt ... voor veel namen zijn afkortingen mogelijk. Je ziet het hierboven al. Library lib, sourcecode src, application app. "Vroeger" was ik nooit zo'n voorstander om afkortingen te gebruiken omdat je dan sommige woorden wel en sommige woorden niet gaat afkorten. Hoe kijken jullie daar tegenaan? Gebruiken jullie in jullie code afkortingen, of schrijf je altijd alles voluit?
Een voorbeeldje:
De functie deleteDirectory() is heel duidelijk, maar ook best lang. Een naam als delDir() is veel korter ... maar is het dan nog duidelijk (genoeg)? Zijn er redenen om wel of geen afkortingen te gebruiken? Of is het (zoals vaak) en kwestie van persoonlijke voorkeur? Of bijv. je wilt de positie van een karakter opslaan. Gebruik je dan de variabele $character_position of $char_pos. Ben benieuwd naar jullie meningen.
$char_position zou ik al niet gebruiken omdat je een _ moet typen, en dat kost de grote moeite om je vinger naar de shift toets te verplaatsen, en dan ook nog de _ toets in te drukken.
Ik zou $cp of $pos gebruiken (en dat is waarschijnlijk geen goede gewoonte) maar dan wel echt voor een zeer locale variabele.
Voor functies gebruik ik altijd CamelCase (kost ook een shift toetsaanslag), maar functienamen kun je vaak overal gebruiken, dus wil ik ze meer descriptive hebben.
Public variabelen of globals, daar verzin ik altijd hele mooie, descriptieve, maar ook zo kort mogelijke namen voor.
Ik gebruik trouwens ook camel case bij variabelen.
Gewijzigd op 13/07/2016 22:41:21 door jan terhuijzen
De een gebruikt dDir(), de ander delDir(), weer een ander deleteDir() en weer een ander deleteDirectoy(). Blijkbaar is er niet echt een conventie, en doet iedereen zomaar wat ie zelf op dat het moment het handigst vindt. Het mooie aan een korte omschrijving als delDir() vind ik dat het lekker compact is, wat Ben ook zegt ... short, sweet en to the point. Maar je moet bij het nalezen dan wel even nadenken wat delDir() ook al weer betekende. Dat probleem heb je bij deleteDirectory() dan weer niet, maar zo'n lange naam maakt je code wel "wolliger". Dus wat is wijsheid ... als die er überhaupt al is betreffende dit onderwerp?
Even wat krenten uit de pap vissen:
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.
Avoid Disinformation
Programmers must avoid leaving false clues that obscure the meaning of code. We should avoid words whose entrenched meanings vary from our intended meaning.
Use Pronounceable Names
Humans are good at words. A significant part of our brains is dedicated to the concept of words. And words are, by definition, pronounceable.
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. […] My personal preference is that single-letter names can ONLY be used as local variables inside short methods. The length of a name should correspond to the size of its scope.
Avoid Encodings
We have enough encodings to deal with without adding more to our burden. Encoding type or scope information into names simply adds an extra burden of deciphering.
Avoid Mental Mapping
Readers shouldn’t have to mentally translate your names into other names they already know. This problem generally arises from a choice to use neither problem domain terms nor solution domain terms.
Class Names
Classes and objects should have noun or noun phrase […]
A class name should not be a verb.
Method Names
Methods should have verb or verb phrase names […]
Accessors, mutators, and predicates should be named for their value and prefixed with get, set, and is according to the javabean standard.
Don’t Be Cute
If names are too clever, they will be memorable only to people who share the author’s sense of humor, and only as long as these people remember the joke.
Pick One Word per Concept
Pick one word for one abstract concept and stick with it.
Use Solution Domain Names
Remember that the people who read your code will be programmers. So go ahead and use computer science (CS) terms, algorithm names, pattern names, math terms, and so forth.
Use Problem Domain Names
When there is no “programmer-eese” for what you’re doing, use the name from the problem domain.
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.
Avoid Disinformation
Programmers must avoid leaving false clues that obscure the meaning of code. We should avoid words whose entrenched meanings vary from our intended meaning.
Use Pronounceable Names
Humans are good at words. A significant part of our brains is dedicated to the concept of words. And words are, by definition, pronounceable.
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. […] My personal preference is that single-letter names can ONLY be used as local variables inside short methods. The length of a name should correspond to the size of its scope.
Avoid Encodings
We have enough encodings to deal with without adding more to our burden. Encoding type or scope information into names simply adds an extra burden of deciphering.
Avoid Mental Mapping
Readers shouldn’t have to mentally translate your names into other names they already know. This problem generally arises from a choice to use neither problem domain terms nor solution domain terms.
Class Names
Classes and objects should have noun or noun phrase […]
A class name should not be a verb.
Method Names
Methods should have verb or verb phrase names […]
Accessors, mutators, and predicates should be named for their value and prefixed with get, set, and is according to the javabean standard.
Don’t Be Cute
If names are too clever, they will be memorable only to people who share the author’s sense of humor, and only as long as these people remember the joke.
Pick One Word per Concept
Pick one word for one abstract concept and stick with it.
Use Solution Domain Names
Remember that the people who read your code will be programmers. So go ahead and use computer science (CS) terms, algorithm names, pattern names, math terms, and so forth.
Use Problem Domain Names
When there is no “programmer-eese” for what you’re doing, use the name from the problem domain.
Quote:
Dus wat is wijsheid ... als die er überhaupt al is betreffende dit onderwerp?
Zoals met zoveel dingen: zo simpel mogelijk, maar niet simpeler.
delDir() is wat mij betreft even duidelijk als deleteDirectory(). Wel (of nog veel) belangrijk(er) is dat namen niet misleidend zijn. Het moet doen wat het zegt (of impliceert) dat (wat) het doet.
Also, listen to Uncle Bob :p.
Thanks voor de toevoeging! Deze "The length of a name should correspond to the size of its scope." is wel erg mooi moet ik zeggen.
@Thomas
>> delDir() is wat mij betreft even duidelijk als deleteDirectory().
Wat zou jij zelf gebruiken? Wat heeft jouw voorkeur en waarom?
Standalone script: delDir() lijkt mij goed genoeg? Denk aan importscript oid. Als je iets vaker dan 1x gebruikt -> maak een functie. Liefst met een omschrijvende naam.
Groter systeem (vaak onderhevig aan conventies): deleteDirectory() of wat er voorgeschreven wordt.
Maar als het een groter systeem betreft werk je vaak/vaker object georiënteerd, dus dan wordt het een delete() methode van een of andere klasse...
Ik kan hier (wederom :p) niet op voorhand zeggen (een eenduidig antwoord geven) wat ik zou gebruiken omdat ik het toepassingsgebied (de context) niet ken.
Het gaat me eigenlijk ook meer om de besluitvorming die eraan ten grondslag ligt. Mijn idee is dat je altijd consistent moet zijn (mee eens?) en dat je dus op verschillende plekken hetzelfde doet.
Op het moment dat je dus in plaats van een class Directory met een method delete() kiest, je kiest voor een class Dir met de method del(), dan vind ik dat je overal in je applicatie of framework voortaan del moet gebruiken ipv delete en dir ipv directory. Het zou dan dus bijv. ook Cache::del() worden en niet Cache::delete(). Cache is echter weer veel korter dan Directory en de noodzaak om het woord te verkleinen is hier weer een stuk minder. Maaaaar ... je kan niet de ene keer del gebruiken en de andere keer delete. Mijn vraag is dus ... wanneer ga je afkorten? Of kun je functienamen gewoon beter helemaal nooit afkorten? Maar wat doe je dan met een functienaam als generateRandomColorScheme(). Laten we dat zo, of maken we daar genRandColScem() van? Om maar eens wat te verzinnen ...
Enne, generateRandomColorScheme() zal niet zo gauw voorkomen, het zal dan eerder iets worden als ColorScheme::generate($mode) ofzo :).
Als een naam "te lang" wordt dan zou er een lampje moeten gaan branden. Mogelijk doet je functie/methode dan te veel of sla je door in het proberen te vangen wat iets doet.
brevity is the soul of wit ;)
Oké ... thanks ... dan maar geen afkortingen haha.
>> Enne, generateRandomColorScheme() zal niet zo gauw voorkomen, het zal dan eerder iets worden als ColorScheme::generate($mode) ofzo :).
Haha, ja klopt ... maar ja, ik moest even iets langs verzinnen. Je begrijpt wat ik bedoel ;-)
Thanks voor de tips en het meedenken.