Share
Als het gaat om het schrijven van code, ongeacht de taal of het platform dat wordt gebruikt, zijn we ontwikkelaars vaak verdeeld over hoe veel of hoe weinig we onze code moeten beoordelen.
Aan de ene kant zijn er mensen die geloven dat die code zelfdocumenterend moet zijn. Dat wil zeggen, het moet zo duidelijk genoeg worden geschreven dat het geen opmerkingen nodig heeft.
Aan de andere kant geloven sommigen dat alles moet worden becommentarieerd. Dat wil zeggen dat er opmerkingen moeten zijn voor elke klas, elke functie, elk blok en elke regel.
Dan zijn er natuurlijk mensen die in het midden vallen. Sommige ontwikkelaars geven zelfs alleen commentaar gebieden van hun code die misschien verwarrend is in plaats van de alles-of-niets-benadering zoals hierboven beschreven.
Als het gaat om het schrijven van code voor WordPress, hebben we de WordPress-coderingsstandaarden om een standaard te bieden waarmee we onze code moeten schrijven; het biedt echter geen sterke argumenten voor of tegen opmerkingen over de code.
In deze reeks artikelen ga ik een zaak voorleggen voor code opmerkingen. Ik ga in het bijzonder in op waarom ze ertoe doen, een aanbeveling voor hoe dit moet in de context van de standaard WordPress-vereiste bestanden (voor zowel thema's als plug-ins) en voor hoe dit te doen voor HTML-bestanden, stylesheets en JavaScript bestanden.
Voordat ik de verschillende onderdelen van een WordPress-project bekijk, denk ik dat het belangrijk is om te bespreken waarom opmerkingen in de code er zelfs toe doen. Natuurlijk weten de meesten van ons dat het een korte uitleg is over wat er met de code aan de hand is, maar de implicaties zijn groter dan dat.
Ondanks het feit dat we normen hebben waarmee we moeten schrijf onze WordPress-gebaseerde code, sommige ontwikkelaars behandelen hen als "aanbevelingen", laat staan degenen die zich er niet eens van bewust zijn. Ongeacht hoe goed (of hoe slecht) je je code schrijft, het is nog steeds zo code.
Immers, als het gemakkelijk te begrijpen was, zou het geen code worden genoemd (en we zouden geen opmerkingen nodig hebben).
Ik geloof niet dat we code-opmerkingen alleen met anderen in gedachten moeten schrijven, ook niet. Ik denk dat we ze net zo goed voor onszelf moeten schrijven. Wanneer je de code voor het eerst opnieuw bezoekt nadat een aanzienlijke hoeveelheid tijd is verstreken, is het zeer waarschijnlijk dat je een betere programmeur bent geworden, een paar nieuwe technieken hebt opgedaan en / of bent overgegaan van hoe je code hebt geschreven. Het kan dus moeilijk zijn om te onderscheiden wat je probeerde te doen.
En als het moeilijk is voor de auteur van de code om te volgen, welke hoop is er dan voor andere ontwikkelaars die de code bijdragen, uitbreiden of verbeteren??
Uiteindelijk moeten opmerkingen worden geschreven aan onszelf en aan anderen die mogelijk onze code gebruiken. Ze moeten duidelijk en beknopt zijn en alle informatie bevatten die een ontwikkelaar nodig zou hebben om te kunnen werken met het gegeven codegedeelte. Dit omvat alle informatie over de verwijzingscode in anders bestanden (zowel aan de server- als aan de clientzijde).
Met dat gezegd, zou ik graag een paar redenen en strategieën bespreken voor het becommentariëren van alle bestanden die betrekking hebben op het maken van een WordPress-thema, -plug-in of -toepassing..
Afhankelijk van uw project, variëren de bestanden die u moet opnemen. Voor de doeleinden van dit artikel ga ik ervan uit dat u PHP-bestanden, HTML-bestanden, stylesheets en JavaScript-bestanden bijvoegt om er zeker van te zijn dat alle bases zijn gedekt. In dit artikel bespreken we de taal aan de serverzijde - dat wil zeggen PHP - en in het volgende artikel zullen we de talen aan de clientzijde bekijken.
Als het gaat om het reageren op onze PHP-bestanden, zijn er verschillende vereisten die we moeten naleven:
Anders dan dit, is er echt weinig commentaar nodig, dus er is duidelijk ruimte voor verbetering.
Als het gaat om het reageren van code in PHP, is er eigenlijk een voorgestelde manier om dit te doen - PHPDoc. Net als de WordPress-codeerstandaarden is PHPDoc een standaard voor het maken van commentaar (of het documenteren van) PHP-code. Het biedt een aantal conventies die allemaal van toepassing zijn op WordPress, maar waarvan ik een deel regelmatig zie gebruiken.
WordPress ondersteunt twee soorten sjabloonbestanden:
Als het gaat om het documenteren van sjabloonbestanden - ongeacht het type sjabloon - probeer ik altijd kopinformatie te geven die de naam van het bestand bepaalt, het doel van het bestand, het pakket - of thema of plug-in - waarvan het deel uitmaakt, en hoe lang het heeft bestaan in het project.
Bijvoorbeeld:
/ ** * Sjabloonnaam: Uitgelichte projecten * * De sjabloon die wordt gebruikt voor het gebied 'Uitgelichte projecten' van de startpagina. Loopt door het berichttype 'Uitgelichte projecten' en haalt de drie meest recente vermeldingen. * * @package Projectthema * @since 1.0 * /
Zoals je kunt zien, heb ik het vereiste verstrekt Sjabloonnaam voor het bestand, maar ik heb ook een korte beschrijving gegeven van wat er in het bestand gebeurt. Ik heb ook het @pakket en @sinds richtlijnen om meer duidelijkheid te geven.
De @pakket richtlijn, ten minste in de context van WordPress, vertegenwoordigt de naam van het thema of de plug-in waarvan dit specifieke bestand deel uitmaakt.
De @sinds richtlijn geeft aan hoe lang de sjabloon in het project heeft bestaan. In het bovenstaande geval is het duidelijk in het project geweest sinds de oorspronkelijke release, maar het is niet ongebruikelijk om bestanden toe te voegen als een thema of plug-in rijpt, wat resulteert in een ander versienummer dat verschijnt als deze waarde.
Vanwege de aard van de basissjabloonbestanden zoals de index, enkele pagina, archiveringssjablonen, enzovoort, hoeft u geen "Sjabloonnaam,"maar de beschrijving, het pakket en de richtlijnen zijn nog steeds relevant.
Documenteringsfuncties lijken sterk op documentatiesjablonen. Hoewel ze geen specifieke tag vereisen, zoals "Sjabloonnaam"- ze moeten nog steeds een beschrijving bevatten van het doel van de functie en de @sinds richtlijn.
Er zijn ook twee aanvullende richtlijnen die een functie optioneel kan bevatten:
Accentsconagua
@param die het type en de beschrijving beschrijft van een parameter die de functie accepteert@return die het type en de beschrijving beschrijft van wat de functie retourneertNatuurlijk accepteren functies niet altijd parameters en functies retourneren niet altijd waarden, vandaar de reden dat deze twee richtlijnen optioneel zijn.
Ervan uitgaande dat u een functie hebt die beide bovenstaande richtlijnen ondersteunt, kunt u het volgende verwachten aan de hand van de documentatie:
/ ** * Voegt een pagina programmatisch in de database in. * * @param $ title De titel van de pagina. De variant in kleine letters dient ook als paginaslak. * @param $ template_name De naam van het sjabloonbestand in de map 'templates'. * @return De ID van de pagina die is gemaakt * @sinds 1.0 * /
Voor meer informatie over elk van deze richtlijnen, kunt u de PHPDoc-tags bekijken; U kunt echter zien hoe nuttig dit kan zijn voor het werken aan een thema of plug-in - het kost u veel pijn om te hoeven onderscheiden wat u of een andere ontwikkelaar met een bepaalde functie probeerde te bereiken.
Hoewel er weinig aanbevelingen of feitelijke normen zijn voor het documenteren van blokken met code, geloof ik nog steeds dat het nuttig is, vooral als het gaat om meer gecompliceerde loops of conditionals.
Dit alles kan worden gedemonstreerd in het volgende voorbeeld: Laten we aannemen dat we een aangepaste query moeten instellen om post-metagegevens door te lussen en deze vervolgens te verwijderen als een bepaalde sleutel en / of waarde wordt gevonden. Dit zou de volgende stappen vereisen:
In dit voorbeeld worden zowel afzonderlijke regels als conditionals gedocumenteerd. Laten we eerst eens naar de broncode kijken en daarna bekijken we wat het precies doet:
// Stel argumenten in om alle gepubliceerde berichten op te halen $ arguments = array ('post_type' => 'post', 'post_status' => 'publiceer', 'nummerposten' => -1); // Start de query $ posts_query = new WP_Query ($ arguments); // Als berichten worden gevonden, doorloop ze als ($ posts_query-> have_posts ()) while ($ posts_query-> have_posts ()) $ posts_query-> the_post (); / * * Bewaar voor elk gevonden stuk post-meta de waarden in * de $ meta_key en $ meta_value die we kunnen controleren. * / foreach (get_post_meta (get_the_ID ()) als $ meta_key => $ meta_value) / * * Er kunnen meerdere meta-sleutels zijn (zoals tweet_url_0, tweet_url_1) * dus we moeten controleren om te zien of de 'tweet_url' zich bevindt in de * $ meta_key. * * Als dit het geval is, kunnen we de post-metadata * / if (false! = Strstr ($ meta_key, 'tweet_url')) delete_post_meta (get_the_ID (), $ meta_key) verwijderen; // end if // end foreach // end while // end if // Stel de aangepaste query opnieuw in zodat deze geen interferentie met andere query's of The Loop wp_reset_postdata (); In het ideale geval moeten de bovenstaande opmerkingen alle documentatie en uitleg bevatten die nodig is om te begrijpen wat er in de code aan de hand is. Misschien is het enige dat nodig kan zijn, begrip van de strstr functie.
Het belangrijkste punt dat ik probeer te maken met de bovenstaande code is dat als we enkele regels documenteren, het het beste is om vast te houden aan de conventie met één regel - dat wil zeggen, de // - maar als we een opmerking schrijven die meerdere regels omvat, is het altijd het beste om de opmerking met meerdere regels te gebruiken, dat wil zeggen, de / * * /.
Merk ook op dat niet elke regel heeft om commentaar te geven. In plaats daarvan kunnen blokken (of stukjes) van de code worden uitgelegd in een commentaar met meerdere regels die documenteert wat er gaat gebeuren in de volgende broncode.
Dit is natuurlijk geen standaard of een voorkeursmanier om dingen te doen. Het is slechts een strategie die ik heb gebruikt, die ik waardeer en die ik zelf gebruik.
Als u de conventies volgt zoals uiteengezet in PHPDoc, zijn er een aantal hulpprogramma's die documentatiepagina's voor uw werk kunnen genereren. Wellicht is de meest populaire tool phpDocumentor.
In het kort, phpDocumentor is een hulpprogramma dat door je broncode gaat op zoek naar goed geformatteerde PHPDoc-codeopmerkingen (met name over klassen en functies), en zal vervolgens een reeks gestileerde pagina's genereren die de informatie in je opmerkingen vastleggen.
Dit maakt verzending ontwikkelaar-georiënteerde documentatie met uw applicatie een makkie.
In dit artikel heb ik besproken waarom ik vind dat code-opmerkingen iets moeten zijn dat alle ontwikkelaars in hun code moeten opnemen. Hoewel de WordPress Codex een basisset met opmerkingen definieert die vereist zijn voor ons werk en / of om te communiceren met de WordPress-applicatie, is er duidelijk meer werk dat we kunnen doen om de helderheid van onze code te verbeteren..
Het punt is dat we er maar de helft van hebben bedekt. Dus, in het volgende artikel zullen we kijken naar het documenteren van markeringen, JavaScript en stijlen.
@pakket Richtlijn@sinds Richtlijnstrstr