Share
In deze tweedelige serie bekijken we hoe we argumenten kunnen formuleren voor opmerkingen over de code. In het eerste artikel hebben we de serverkant behandeld door PHP te bekijken. We hebben met name PHPDoc-conventies besproken en hoe je ze kunt gebruiken om sjablonen, functies en regels en blokken te documenteren.
In dit artikel gaan we kijken naar client-side talen. Concreet gaan we kijken naar HTML, CSS en JavaScript.
Hoewel er niet noodzakelijk documentatiehulpprogramma's zijn zoals phpDocumentor voor al deze talen, zijn er nog steeds strategieën die we kunnen gebruiken om het onderhoud van onze projecten (of anderen helpen bijdragen aan onze projecten) een beetje gemakkelijker te maken.
Als het gaat om het werken met WordPress, zullen thema's en plug-ins variëren in het type bestanden dat ze bevatten. Thema's zullen meestal bestaan uit HTML en CSS en waarschijnlijk wat JavaScript, terwijl plug-ins mei bestaat alleen uit PHP.
In het eerste artikel hebben we gekeken naar wat WordPress vereist om sjabloonbestanden te registreren bij de API en welke plug-ins vereist zijn. Voordat ik verder lees, raad ik aan dat artikel eerst te lezen omdat het de vereiste informatie bevat, terwijl dit specifieke artikel alleen aanbevelingen gaat doen voor wat we kunnen doen om onze opmerkingen te verbeteren..
De meeste webontwikkelaars zijn zich bewust van hoe ze opmerkingen kunnen schrijven in de context van HTML. Gewoon, het is een kwestie van het vooraf invoeren van de code - of het nu een enkele regel of blok is - met . Als het gaat om het schrijven van markeringen, is het niet erg gebruikelijk om opmerkingen te zien die verder gaan dan conditionals die je misschien in de hoofd element van het document.
Er zijn technieken die we kunnen gebruiken om onze code beter te onderhouden. Dit is vooral handig als u met systemen zoals WordPress werkt, omdat bepaalde elementen over meerdere bestanden worden verspreid.
Als je bijvoorbeeld ervan uitgaat dat je een thema aan het maken bent, ga je waarschijnlijk je eigen account openen lichaam element en een containerelement in de header.php sjabloon en vervolgens de elementen in de footer.php sjabloon.
Dit is een beetje een vereenvoudigd voorbeeld, omdat het relatief vaak voorkomt, maar het principe blijft waar door de andere bestanden.
Met dat gezegd, is er een eenvoudige strategie die we kunnen gebruiken voor het becommentariëren van onze code:
HTML-elementen zijn over het algemeen in een van de vier vormen:
Voor elk van deze permutaties volg ik de volgende conventies:
Hierboven is er een codefragment voor een formulier dat wordt gebruikt om opties op te slaan in het WordPress-databasevorm in het Dashboard. In dit geval laat ik normaal gesproken een opmerking achter aan het element die het doel van het formulier of een ander kenmerk aangeeft, zoals het actiekenmerk.
Gezien die strategie, ziet het bovenstaande voorbeeld er ongeveer zo uit:
Of:
De conventie die ik kies om te gebruiken is om een backslash te gebruiken - op een normale HTML-manier - gevolgd door het doel van de beschrijving van het element om me te laten weten dat ik het element beëindig.
Hoewel dit misschien niet zo handig is met een enkel geïsoleerd element, vind ik het nuttig om zowel geneste elementen te gebruiken als wanneer een element - zoals een container - over bestanden wordt gesplitst.
In het geval dat het element een ID heeft, gebruik ik de volgende opmerking:
Net als hierboven gebruik ik een backslash gevolgd door een '#'dat een ID in CSS voorstelt gevolgd door de naam van de waarde van het ID-attribuut. Dit laat me weten dat ik een element beëindig met het opgegeven ID.
Nogmaals, dit is vooral handig wanneer een element bestaat uit meerdere bestanden, maar het is ook handig als je een globale zoekopdracht moet doen in sjabloonbestanden of in CSS-bestanden..
Wanneer een element alleen een klasse (of een reeks klassen) bevat, volg ik een vergelijkbare strategie als hierboven: ik gebruik een backslash, de CSS-indicator voor een klasse en vervolgens de klasse (of de eerste klas) voor het element:
Simpel genoeg.
Maar wat gebeurt er als het element zowel een ID als een klasse bevat? Omdat ID's uniek zijn en classnames niet, gebruik ik altijd de ID van het element bij het beëindigen van de opmerking:
Klinkt logisch, toch? En het punt blijft nog steeds: dit maakt het gemakkelijk om te weten welk element ik eindig en maakt het gemakkelijk om het te vinden in de rest van de projectbestanden.
JavaScript lijkt op PHP, omdat het functies van een hogere orde ondersteunt, zoals functies (en prototypen als je vanille JavaScript schrijft). Daarom is het nuttig om een conventie te hebben waarmee we onze functies documenteren.
Hier is het volgende: WordPress bevat standaard jQuery, dus het is gebruikelijk dat de meeste WordPress-specifieke JavaScript wordt geschreven met een combinatie van jQuery-gebaseerde JavaScript en vanille-gebaseerde functies zoals functies.
De volgende strategieën zijn nuttig gebleken bij het schrijven van JavaScript in WordPress:
Eerst probeer ik het bestand een naam te geven op basis van het doel dat het dient (zoals navigation.js of theme.js of admin.js).
Ten tweede zal ik ook een korte beschrijving aan de bovenkant van elk bestand geven met behulp van PHPDoc-conventies voor het beschrijven van het bestand en hoe lang het deel uitmaakte van het project:
/ ** * admin.options.js * * Beheer van de gebeurtenishandlers voor verschillende elementen op de pagina Dashboardopties. * * @since 1.0 * @version 3.2 * /
Voor functies volg ik een vergelijkbare conventie als hierboven, waarin ik een korte beschrijving van de functie geef, beschrijf wat deze accepteert en wat deze oplevert, evenals hoe lang het in het project en de huidige versie van het bestand is geweest:
/ ** * Helper-functie die wordt geactiveerd wanneer de gebruiker op 'Gereed' klikt of op 'Enter' * klikt om zijn sociale pictogrammen op te slaan. * * @param $ Een verwijzing naar de functie jQuery * @param evt De brongebeurtenis van deze handler * @ retourneert of de gebruiker op enter moet drukken of annuleren om zijn opties op te slaan. * @since 1.0 * @version 1.2 * /
Dit is eigenlijk niets meer dan standaardcodereacties die de meeste ontwikkelaars vaak gebruiken. Er is de single line-variant, de multiline-variant en het doel dat ze dienen: dat wil zeggen, gewoon om te beschrijven wat er gaat gebeuren in de code na de opmerking.
Accentsconagua
/ * * Als we naar het pictogram voor RSS-feeds kijken, schakel dan de invoer * uit en koppel de gebruiker aan de algemene opties voor waar dit moet worden ingesteld. * / if ("! == sRssUrl) $ ('# social-icon-url') .val (sRssUrl) .attr ('disabled', 'disabled'); else $ ('# social-icon- url '). removeAttr (' disabled '); // end if Er is hier weinig toe te voegen die ik in het eerste artikel niet heb behandeld, maar ik wilde het hier ter beoordeling vermelden en volledig zijn.
Hoewel er geen officiële JavaScript-documentatietool is, is jsDoc een van de meest gebruikte hulpprogramma's geworden voor het documenteren van JavaScript-code.
CSS-bestanden reageren is beslist veel gemakkelijker dan werken met PHP of met markeringen, omdat er maar één manier is om stijlen te schrijven.
Dat wil zeggen, u definieert stijlen voor een element met behulp van een ID of een klasse:
# geen-reacties font-size: 24px; regelhoogte: 36px; lettertype: vet; kleur: # 444;
Of:
..sticky: vóór display: inline-block; achtergrond: transparante URL (images / sticky.png) zonder herhaling; breedte: 58px; hoogte: 45 px; inhoud: ""; positie: absoluut; top: 26px; links: -9px;
In het algemeen denk ik niet dat je commentaar moet geven op stijlen, maar als je merkt dat de afsluitende haakjes buiten beeld zijn, dan kan het handig zijn om de stijl te eindigen met een opmerking als deze:
# geen-reacties font-size: 24px; regelhoogte: 36px; lettertype: vet; kleur: # 444; /* #geen commentaar */
Of:
..sticky: vóór display: inline-block; achtergrond: transparante URL (images / sticky.png) zonder herhaling; breedte: 58px; hoogte: 45 px; inhoud: ""; positie: absoluut; top: 26px; links: -9px; / * .home .sticky: voor * /
Op dit moment wordt het gebruik van talen zoals LESS en Sass en hun respectievelijke preprocessors steeds populairder in webontwikkeling. Een van de meest voorkomende kenmerken van deze twee talen is dat ze geneste regels ondersteunen.
In dit geval denk ik dat er een veel sterkere reden is om opmerkingen te gebruiken. Bijvoorbeeld:
#header #slideshow # image-list list-style: none; zweven: links; marge: 0; breedte: 100%; // # image-list // #slideshow // #header
Op deze manier weet je welk element je beëindigt, ongeacht waar het element begint in de IDE.
In deze reeks heb ik uiteengezet waarom ik vind dat code-opmerkingen iets moeten zijn dat alle ontwikkelaars in hun code moeten opnemen. In dit artikel heb ik mijn strategieën besproken voor hoe ik commentaar geef op mijn markeringen, mijn JavaScript en mijn stijlen.
Hoewel ik niet zeg, is mijn manier de enkel en alleen manier om opmerkingen te schrijven - het is maar één manier - ik geloof dat het opnemen van opmerkingen een lange weg gaat om een project beter te onderhouden voor uzelf en uw collega's, en ik denk dat het opnemen van hen in uw werk iets is dat elke ontwikkelaar moet nastreven.
Hopelijk heeft deze serie daar juist voor gezorgd. Hoe dan ook, ik hoor graag uw mening en suggesties in de opmerkingen.
