PHP Coding Richtlijnen

[Guru Evi]

Hello,

Ik ben bezig met een open source programma te maken. We zijn ondertussen al aan versie 2.0 en we komen nu in de puree vanwege het volgende:

We hebben spaans-sprekende en engels-sprekende developers en ook een hoopje anders-sprekende vertalers. Hierdoor hebben we een hoop functies en variablen die allemaal verschillende namen hebben, sommige volledig spaans, sommige slecht engels en sommige goed engels.

We zijn dus nu richtlijnen aan het samenstellen voor de rest van de community. We hebben ongeveer 5 programmeurs die allemaal implementeren wat ze zelf nodig hebben.

We hebben al het volgende voorgesteld:
- Alle functies en variablen in het Engels
- Opsplitsen van functies over verschillende bestanden (users, groups, modules, db, ...)
- Commentaren moeten boven functies en allemaal hetzelfde eruitzien
- Geen gebruik maken van ImageMagick, GD of MySQL inline, ze moeten allemaal in functies zitten zodat we ze later kunnen verplaatsen met betere of andere libraries.
- Variablen moeten allemaal hetzelfde worden geinitializeerd (-1 voor signed integers, 0 voor signed, "" voor strings, array () voor arrays)
- Wanneer functies worden geassigneerd aan een variable, moet de verwachte type output ook aangeduid worden ($group = (int) get_group ($user);)

Zijn er nog andere zaken die we over het hoofd zien die je in een internationaal project moet opnemen of in het algemeen die ervoor zorgen dat buitenstaanders gemakkelijk kunnen de draad oppikken.

En dan van de andere kant, hoe ga je dit implementeren in zo'n 210 reeds geschreven bestanden? Ik kan met XCode een search-and-replace doen op functies die reeds gebruikt zijn in het project maar vooral het veranderen en opsplitsen van bepaalde functies is waar ik mij over verwonder.

[Kettrick]

Java/Eclipse heeft hiervoor een tooltje genaamd checkstyle, mogelijk doet dat wat je wil met wat andere regels ?

[BtM909]

Zoek eens met Google naar Coding standards en kijk naar bestaande modellen?

Je moet het wel even top-down aanpakken... Dus bijvoorbeeld je methodiek (MVC pattern), daarna door naar functionaliteit en hoe te groeperen vervolgens framework (of layout of template) van functies, commentaren en tot slot variabelen.

- Geen gebruik maken van ImageMagick, GD of MySQL inline, ze moeten allemaal in functies zitten zodat we ze later kunnen verplaatsen met betere of andere libraries.

Ik neem aan dat je bedoelt dat je bijvoorbeeld een wrapper hiervoor schrijft?

[CH4OS]

Waar je eventueel ook naar zou kunnen zoeken is OOP, oftewel Object Oriented Programming...
Wellicht dat dat je ook een eind kan helpen...

[Kettrick]

GJtje schreef op donderdag 23 oktober 2008 @ 22:10:
Waar je eventueel ook naar zou kunnen zoeken is OOP, oftewel Object Oriented Programming...
Wellicht dat dat je ook een eind kan helpen...

Ook dan is het belangrijk om goede afspraken te maken, anders wordt dat evengoed een zootje

OO betekend ( helaas ) niet dat een applicatie meteen netjes is

[CH4OS]

RoeLz schreef op donderdag 23 oktober 2008 @ 22:13:
Ook dan is het belangrijk om goede afspraken te maken, anders wordt dat evengoed een zootje

OO betekend ( helaas ) niet dat een applicatie meteen netjes is

Dat ben ik met je eens, maar ik zie de TS ook niet zeggen of ze überhaupt gebruik maken van OOP of niet... Aangezien ik wel lees, dat ze een dergelijke opzet wel willen gaan maken.

[Erikie]

GJtje schreef op donderdag 23 oktober 2008 @ 22:10:
Waar je eventueel ook naar zou kunnen zoeken is OOP, oftewel Object Oriented Programming...
Wellicht dat dat je ook een eind kan helpen...

er zitten inderdaad een hoop voordelen aan oop aanpak, het ding werkt, (of niet ) en je hebt er geen omkijken meer naar, tenzij je later natuurlijk gaat interfacen en extenden enzo. Maar dan nog heb je je wel te houden aan een aantal php coding richtlijnen, en het belangrijkste nog, het documenteren van je classes etc. Dan zou die spaanse in principe zijn classes in het spaans kunnen schrijven, als zijn documentatie maar engels is. dan vervolgens met phpdoc eroverheen gaan en je hebt een handleiding van je php code die iedereen kan lezen en begrijpen.

Ik weet natuurlijk niet wat je gaat coden, maar misschien is een frameworkje wel relaxt. zoals zend framework (1.6) en een goeie ide (zend studio 6+ bijvoorbeeld, gaat je wel wat hoofdpijn bezorgen, maar als t eenmaal werkt is het uitermate geschikt voor lekker groepscoden). Deze maakt ook automatisch (als je wil) php documentatie aan van je classen enzo, maar waarschijnlijk zijn er genoeg andere ide's die daar ook wat moois van maken.

Voor coding standards zou je deze richtlijnen kunnen nastreven : http://framework.zend.com/manual/en/coding-standard.html

't is wel ff wat leesvoer, maar ik vind het persoonlijk een erg nette aanpak van je code en vrij standaard.

[Jaap-Jan]

Een (ander) voorbeeld van een bestaande codestyle voor PHP, is de codestyle van Roundcube: http://trac.roundcube.net/wiki/Dev_Guidelines. Niet specifiek voor internationaal publiek (afgezien dat alle identifiers in het Engels moeten), maar wel een redelijk idee voor waar je aan kan denken.

Wat misschien ook wel kan helpen is de codestyle voor Python. Hoe je commentaar moet schrijven kan nuttig zijn, maar een paar dingen die nuttig kunnen zijn, met name voor internationaal publiek:
• "A Foolish Consistency is the Hobgoblin of Little Minds". Als je een goede reden hebt om af te wijken van de standaard, bijvoorbeeld omdat het de leesbaarheid verbetert, doe dat dan.
• Namen (van personen) met vreemde tekens moeten ook in Latin-1 (ISO-8859-1) geschreven worden
• Commentaar moet de code niet tegenspreken, in grammaticaal correct Engels zijn (Strunk & White), maar wel kort en bondig
• Variabelennamen het liefst in het Engels (afkortingen en vaktermen/ technische termen kunnen een uitzondering vormen).

[ Voor 60% gewijzigd door Jaap-Jan op 24-10-2008 00:44 ]

[Kalentum]

Guru Evi schreef op donderdag 23 oktober 2008 @ 21:44:
En dan van de andere kant, hoe ga je dit implementeren in zo'n 210 reeds geschreven bestanden? Ik kan met XCode een search-and-replace doen op functies die reeds gebruikt zijn in het project maar vooral het veranderen en opsplitsen van bepaalde functies is waar ik mij over verwonder.

Ik denk dat de kans op niet-werkende code groot is. Ik zou afspreken met iedereen dat nieuwe commits voldoen aan de nieuwe standaard. Dus zowel nieuwe code als wijzigingen op bestaande code Dat is ook eenvoudig te controleren. Je bent dan stap voor stap aan het herschrijven.