|
Richtlijnen voor scripts.
|
| Deze richtlijnen worden gebruikt voor het keuren van een script. De richtlijnen vertellen niet expliciet hoe een script eruit moet zien maar helpen je bij het keuren van een goed script. |
| |
 Richtlijn 1 |
| Een script is een werkend stuk code dat andere leden kunnen gebruiken. De code is ook goed geschreven en is geen hoopje instructies bij elkaar gegooid. OO code moet voldoen aan de OO principes. |
| Richtlijn 2 |
| Een script is makkelijk te integreren in een bestaande applicatie. Gebruikers willen dat het script makkelijk werkt in hun applicatie zonder dat ze het moeten veranderen. |
| Richtlijn 3 |
| Een script in een bepaalde scripttaal zoals Javascript, PHP, ... is ook enkel in die taal geschreven. Er wordt dus geen HTML code verwacht omdat de auteur geen expliciete layout mag opleggen aan de gebruiker. Dit zou de gebruiker zijn bestaande applicatie kunnen schaden. |
| Richtlijn 4 |
| Een script heeft altijd een apart voorbeeld code fragment. Hierin kan wel HTML gebruikt worden waar dit in puntje drie niet mocht. |
| Richtlijn 5 |
| Bij code wordt enkel code fragmenten geplaatst. Erboven kan een woordje of korte zin met uitleg (bv “Voorbeeld 1: .....”). |
| Richtlijn 6 |
| Onder de titel komt de uitleg van het script. De uitleg van een script bevat de volgende dingen. |
| Richtlijn 6.1 |
| Geen “hallo” of “dankjewel” of “dit is een fantastische script”. Objectieve inhoud dus. |
| Richtlijn 6.2 |
| De functie van het script. De features worden mooi in een lijstje of paragraaf uitgetypt. Indien het een functie is of een klasse script, worden de parameters en return waarden netjes gedocumenteerd. Geen code voorbeelden, zie punt vier. |
| Richtlijn 6.3 |
| In een tweede paragraaf kan uitgelegt worden hoe je script kan gebruiken in de gebruiker zijn applicatie. Vermeld ook dat bepaalde bibliotheken worden gebruikt. Bijvoorbeeld jQuery in je script of PEAR in PHP. |
| Richtlijn 6.4 |
| In een derde paragraaf kan vermeld worden dat het script bepaalde variabelen gebruikt die kunnen schaden voor bestaande code. Stel dat ik een script gebruik met de variabele $_SESSION['naam'] en in me applicatie gebruik ik dat ook, dan zou dat script me applicatie kunnen schaden. |
| Richtlijn 6.5 |
| De originele auteur met link naar de auteur zijn werk. |
|
| Richtlijn 7 |
| Libraries die gebruikt worden moeten meegeleverd worden in een download. |
| Richtlijn 8 |
| Er is altijd een download beschikbaar voor de gebruiker. Indien gewenst kan dit worden gemaakt door de moderator en gehost op de server van sitemasters. |
| Richtlijn 9 |
| Indien het gaat om functie(s) of klasse(s) wordt alles gedocumenteerd in de code op een nette manier. De code layout is netjes en leesbaar (enters, spaties en tabs). |
| Richtlijn 10 |
| Indien de codefragmenten te lang zijn of er zijn teveel codefragmenten, kan er worden verwezen naar de download. Dit gebeurt niet in de code sectie maar in de uitleg sectie in de voorlaatste of laatste paragraaf. |
| Richtlijn 11 |
| De uitleg wordt in algemeen nederlands geschreven. Commentaar in de code kan in algemeen nederlands of in het engels geschreven zijn. |
| Richtlijn 12 |
| De volgende punten geldt voor grote systemen als een forum, fotoalbum, ... |
| Richtlijn 12.1 |
| Er mag een stijl/layout bij zijn zolang HTML, CSS en PHP mooi gescheiden zijn. |
| Richtlijn 12.2 |
| Er is documentatie meegelevert bij de download. |
| Richtlijn 12.3 |
| Bij code fragment kan een voorbeeld staan, bv een example van het configuratiebestand. Geen code van het systeem. |
| Richtlijn 12.4 |
| Er is een duidelijke mappenstructuur. |
|
| Richtlijn 13 |
Indien er verbeteringen aan het script gebeurt zijn, wordt dit vermeld onder de derde paragraaf. Dus in de vierder paragraaf komt de changelog als die er is. Een lijstje met de datum en versienummer en wat de verbeteringen zijn in een sublijstje. Voorbeeld:
- Versie 1.1 (12 oktober 2008):
- [filename:] verandering 1
- [filename:] verandering 2
- Versie 1.0 (10 oktober 2008)
|
