Broncodering Commentaar Stylingtips en beste praktijken

Ontwikkelaars die zich altijd hebben beziggehouden met grote projecten begrijpen het belang van codereacties. Wanneer u veel functies in dezelfde toepassing bouwt, wordt de situatie vaak gecompliceerd. Er zijn zoveel gegevensbits, inclusief functies, variabele referenties, retourwaarden, parameters ... hoe moet je het bijhouden?

Het is geen verrassing dat het belangrijk is om commentaar te geven op je code, zowel voor solo- als voor teamprojecten. Maar veel ontwikkelaars weten niet hoe ze dit proces moeten aanpakken. Ik heb enkele van mijn eigen persoonlijke trucs geschetst het maken van nette, geformatteerde opmerkingen over de code. Normen en reactiesjablonen verschillen per ontwikkelaar, maar uiteindelijk moet je ernaar streven schone en leesbare opmerkingen om verwarrende gebieden in uw code nader toe te lichten.

We moeten beginnen met het bespreken van enkele van de verschillen in opmaak van opmerkingen. Dit geeft je een beter idee van hoe gedetailleerd je kunt worden met projectcode. Daarna zal ik een aantal specifieke tips en voorbeelden geven die je meteen kunt gebruiken!

Comment Styles: een overzicht

Opgemerkt moet worden dat deze gepresenteerde ideeën slechts zijn richtlijnen naar schonere opmerkingen. De afzonderlijke programmeertalen bevatten geen richtlijnen of specificaties voor het instellen van uw documentatie.

Dat gezegd hebbende, hebben hedendaagse ontwikkelaars zich gegroepeerd om hun eigen systeem van codecommentaar op te stellen. Ik zal een paar reguliere stijlen aanbieden en gedetailleerd ingaan op hun doel.

Inline commentaar

Vrijwel elke programmeertaal biedt inline opmerkingen. Deze zijn beperkt tot inhoud met één regel en becommentariëren alleen de tekst na een bepaald punt. Dus bijvoorbeeld in C / C ++ begin je een inline commentaar zoals dit:

// begin variabele lijst var myvar = 1; ... 

Dit is perfect om een ​​paar seconden in de code te chanten uitleg over mogelijk verwarrende functionaliteit. Als u met veel parameters of functie-aanroepen werkt, kunt u een hoop inline opmerkingen plaatsen in de buurt. Maar het meest nuttige gebruik is een eenvoudige verklaring voor kleine functionaliteit.

if (callAjax ($ params)) // voer callAjax met gebruikersparameters uit ... code

Merk vooral op dat de code na de openingsbracket op een nieuwe regel moet staan. Anders zou het allemaal op dezelfde commentaarlijn staan! Vermijd overboord te gaan aangezien u over het algemeen geen opmerkingen van één regel hoeft te zien op uw pagina, maar vooral voor verwarrende kruispunten in uw code, zijn deze veel lastiger om op het laatste moment te laten vallen.

Beschrijvende blokken

Wanneer u een grote uitleg moet opnemen, zal een enkele voering meestal niet werken. Er zijn voorgeformatteerde opmerkingensjablonen die worden gebruikt in ongeveer elk programmeergebied. Beschrijvende blokken zijn vooral zichtbaar rond functies en bibliotheekbestanden. Wanneer u een nieuwe functie instelt, is het een goede gewoonte om dit te doen voeg een beschrijvend blok toe boven de aangifte.

/ ** * @desc opent een modaal venster om een ​​bericht weer te geven * @param string $ msg - het bericht dat moet worden weergegeven * @return bool - succes of fout * / functie modalPopup ($ msg) ... 

Hierboven ziet u een eenvoudig voorbeeld van een beschrijvende functiecommentaar. Ik heb een functie geschreven die vermoedelijk in JavaScript is genoemd ModalPopup waarvoor een enkele parameter nodig is. In de opmerkingen hierboven heb ik een syntaxis gebruikt die lijkt op phpDocumentor, waarbij elke regel wordt voorafgegaan door een @ symbool gevolgd door een geselecteerde toets. Deze gaan je code op geen enkele manier beïnvloeden, dus je zou kunnen schrijven @Omschrijving in plaats van @desc zonder enige verandering.

Deze kleine toetsen worden eigenlijk gebeld commentaar tags die zijn gedocumenteerd zwaar op de website. Voel je vrij om je eigen make-up te maken en deze tijdens je code te gebruiken zoals je wilt. Ik merk dat ze helpen om alles zo te laten stromen Ik kan belangrijke informatie in een oogopslag bekijken. Je zou ook moeten opmerken dat ik de / * * / blokstijl commentaaropmaak. Dit zal alles houden veel schoner dan het toevoegen van een dubbele schuine streep die begint bij elke regel.

Groeps- / klas-opmerkingen

Afgezien van het commentariëren van functies en lussen, worden blokgebieden niet zo vaak gebruikt. Waar je echt behoefte aan hebt opmerkingen blokkeren staan ​​aan de kop van uw back-enddocumenten of bibliotheekbestanden. Het is gemakkelijk om alles uit te voeren en gedegen documentatie te schrijven voor elk bestand op uw website - we kunnen deze praktijk in veel CMS bekijken, zoals WordPress.

Het bovenste gedeelte van uw pagina moet opmerkingen bevatten over het bestand zelf. Op deze manier kunt u controleer snel waar je aan het bewerken bent wanneer u op meerdere pagina's tegelijkertijd werkt. Bovendien kunt u dit gebied gebruiken als een database voor de belangrijkste functies die u nodig hebt uit de klas.

/ ** * @desc deze klasse bevat functies voor gebruikersinteractie * voorbeelden omvatten user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / abstracte klasse myWebClass  

Je kunt zien dat ik slechts een kleine voorbeeldklasse heb gebruikt voor de nep myWebClass code. Ik heb wat meta-informatie toegevoegd met mijn naam en e-mailadres voor contact. Wanneer ontwikkelaars open source-code schrijven, is dit over het algemeen een goede gewoonte, zodat anderen contact met u kunnen opnemen voor ondersteuning. Dit is ook een solide methode bij het werken in grotere ontwikkelteams.

Het etiket @verplicht is niet iets dat ik elders heb gezien. Ik heb het formaat in enkele van mijn projecten bijgehouden, alleen op pagina's waar ik veel methoden heb aangepast. Telkens wanneer u pagina's in een bestand opneemt, moeten deze worden weergegeven voordat u een code uitvoert. Dus het toevoegen van deze details aan het opmerkingenblok van de hoofdcategorie is een goede manier om dit te doen onthoud welke bestanden nodig zijn.

Front-end code commentaar

Nu we drie belangrijke reactiesjablonen hebben besproken, laten we nog een paar andere voorbeelden bekijken. Er zijn veel ontwikkelaars van frontend die zijn overgestapt van statische HTML naar jQuery en CSS-code. HTML-opmerkingen zijn niet zo doelgericht in vergelijking met programmeertoepassingen, maar wanneer u stijlbibliotheken en paginascripts schrijft, kunnen dingen na verloop van tijd rommelig worden.

JavaScript volgt een meer traditionele methode van commentaar vergelijkbaar met Java, PHP en C / C++. CSS maakt alleen gebruik van de opmerkingen in blokstijl die worden aangegeven door een schuine streep en een sterretje. Vergeet niet dat reacties openlijk worden getoond aan uw bezoekers, aangezien noch CSS noch JS aan de serverkant wordt geparseerd, maar elk van deze methoden werkt uitstekend om informatieve weetjes in uw code achter te laten om opnieuw te gaan.

Specifiek het opsplitsen van CSS-bestanden kan een hele klus zijn. We zijn allemaal bekend met het achterlaten van een inline-commentaar om een ​​oplossing voor Internet Explorer of Safari uit te leggen. Maar ik geloof dat CSS-commentaar kan worden gebruikt op het niveau dat jQuery en PHP gebruiken. Laten we ons verdiepen in het maken van stijlgroepen voordat we enkele gedetailleerde tips voor het reageren op codes bespreken.

CSS-stijlgroepen

Voor degenen die al jaren CSS ontwerpen, komt het bijna als een tweede natuur. Je onthoudt langzaam alle eigenschappen, syntaxis en bouw je eigen systeem voor stylesheets. Door mijn eigen werk heb ik gemaakt wat ik noem groepering om vergelijkbare CSS-blokken in één gebied te combineren.

Wanneer ik terug ga naar het bewerken van CSS, kan ik binnen een paar seconden gemakkelijk vinden wat ik nodig heb. De manier waarop je kiest om stijlen te groeperen, is geheel aan jou, en dat is het mooie van dit systeem. Ik heb een paar vooraf ingestelde standaarden die ik hieronder heb beschreven:

• @resets - wegnemen van standaardbrowsermarges, opvulling, lettertypen, kleuren, enz.
• @fonts - alinea's, kopjes, blockquotes, links, code
• @navigation - de belangrijkste navigatielinks van de website
• @layout - wrapper, container, sidebars
• @header & @footer - deze kunnen variëren op basis van uw ontwerp. Mogelijke stijlen omvatten links en ongeordende lijsten, voettekstkolommen, koppen, sub-navs

Bij het groeperen van stylesheets heb ik de coderingssysteem kan veel helpen. In tegenstelling tot PHP of JavaScript gebruik ik echter een single @groep tag gevolgd door een categorie of trefwoorden. Ik heb 2 voorbeelden hieronder toegevoegd, zodat je een idee krijgt van wat ik bedoel.

/ ** @group-voettekst * / #footer styles ...

/ ** @group-voettekst, kleine lettertypen, kolommen, externe links ** / 

U kunt ook een beetje extra detail toevoegen in elk commentaarblok. Ik kies ervoor houd de dingen eenvoudig en duidelijk dus de stylesheets zijn eenvoudig af te lezen. Bij opmerkingen gaat het allemaal om documentatie, zolang je het schrijven begrijpt, is het goed om te gaan!

4 Tips om Styling beter te beoordelen

We hebben de eerste helft van dit artikel besteed aan het bekijken van de verschillende indelingen voor codecommentaar. Laten we nu enkele algemene tips bespreken om uw code schoon, georganiseerd en gemakkelijk te begrijpen te houden.

1. Houd alles leesbaar

Soms vergeten we dat als ontwikkelaars we schrijven reacties voor mensen om te lezen. Alle programmeertalen die we begrijpen zijn gebouwd voor machines, dus het kan vervelend zijn om te zetten in gewone geschreven tekst. Het is belangrijk om op te merken dat we hier niet zijn om een ​​onderzoekspaper op universiteitsniveau te schrijven, maar gewoon tips achterlaten!

functie getTheMail () // code hier zal e-mail / * run code bouwen als onze aangepaste sendMyMail () functie aanroep levert true find sendMyMail () terug in /libs/mailer.class.php we controleren of de gebruiker alle velden invult en bericht is verzonden! * / if (sendMyMail ()) return true; // blijf waar en toon succes op het scherm

Zelfs maar een paar woorden zijn beter dan niets. Wanneer u in de toekomst weer projecten gaat bewerken en bewerken, is het vaak verrassend hoeveel u zult vergeten. Aangezien u niet elke dag naar dezelfde variabelen en functienamen kijkt, neigt u ertoe om de meerderheid van uw code langzaam te vergeten. Zo kunt u laat nooit teveel reacties achter! Maar je kunt te veel slechte opmerkingen achterlaten.

Als algemene vuistregel, neem even de tijd om te pauzeren en na te denken voordat je schrijft. Vraag jezelf wat is het meest verwarrend over het programma en hoe kan je het het best uitleggen? “pop” taal? Overweeg ook waarom je de code precies zo schrijft als je bent.

Enkele van de meest verwarrende fouten verschijnen wanneer u het doel van op maat gemaakte (of externe) functies bent vergeten. Laat een commentaarpad achter dat teruggaat naar een paar andere bestanden als dit je helpt de functionaliteit gemakkelijker te onthouden.

2. Verlicht enige ruimte!

Ik kan niet genoeg benadrukken hoe belangrijk witte ruimte kan zijn. Dit gaat dubbel waar voor PHP- en Ruby-ontwikkelaars die werken aan enorme websites met honderden bestanden. Je zult de hele dag naar deze code staren! Zou het niet geweldig zijn als je gewoon door kon naar de belangrijke gebieden?

$ dir1 = "/ home /"; // stel main home directory $ myCurrentDir = getCurDirr () in; // stel de huidige gebruikersdirectory $ userVar = $ get_username () in; // huidige gebruikersnaam van gebruiker

In het bovenstaande voorbeeld zie je de extra opvulling die ik heb geplaatst tussen opmerkingen en code op elke regel. Terwijl u door bestanden bladert, zal deze stijl van commentaar doen duidelijk opvallen. Het maakt het vinden van fouten en het honderden keren eenvoudiger corrigeren van uw code wanneer variabele blokken zo zijn schoon.

Je zou een vergelijkbare taak kunnen uitvoeren op de code in een functie waar je niet zeker weet hoe het werkt, maar deze methode zou je code uiteindelijk volproppen met inline reacties, en dat is precies het tegenovergestelde van ordentelijk! Ik adviseer in dit scenario het toevoegen van een grote blokkeringsreactie rond het gebied van logica.

$ (document) .ready (function () $ ('. sub'). hide (); // verberg de subnavigatie op pageload / ** controleer voor een klikgebeurtenis op een anker binnen .itm div om de standaardlink te voorkomen actie dus de pagina verandert niet op klik toegang tot het bovenliggende element van .itm gevolgd door de volgende .sub lijst om te schakelen openen / sluiten ** / $ ('. itm a'). live ('klik', functie (e ) e.preventDefault (); $ (this) .parent (). next ('. sub'). slideToggle ('fast');););

Dit is een klein beetje jQuery-code gericht op een schuifmenu van het submenu. De eerste opmerking is in lijn om uit te leggen waarom we alle verbergen .sub klassen. Boven de live klikgebeurtenishandler heb ik een blokcommentaar gebruikt en ingesprongen al het schrijven op hetzelfde punt. Dit maakt dingen mooier in plaats van doorlopende alinea's - vooral voor anderen die uw opmerkingen lezen.

3. Reageer tijdens het coderen

Samen met de juiste tussenruimte kan dit een van de beste gewoontes zijn om in te stappen. Niemand wil teruggaan over hun programma nadat het werkt en elk stuk documenteren. De meesten van ons willen niet eens teruggaan en de verwarrende gebieden documenteren! Het kost echt veel werk.

Maar als u de opmerkingen kunt schrijven terwijl u codeert alles zal nog vers in je geest zijn. Gewoonlijk blijven ontwikkelaars vastzitten aan een probleem en doorzoeken het web naar de gemakkelijkste oplossing. Wanneer je het Eureka-moment raakt en een dergelijk probleem oplost, is er over het algemeen een moment van duidelijkheid waarin je je eerdere fouten begrijpt. Dit zou het zijn beste tijd om open en eerlijke opmerkingen over uw code achter te laten.

Bovendien geeft dit je de gewoonte om te wennen aan het reageren op al je bestanden. De hoeveelheid tijd die nodig is om terug te gaan en erachter te komen hoe iets werkt, is veel groter nadat je de functie al hebt gebouwd. Zowel je toekomstige zelf als je teamgenoten zullen je bedanken voor het achterlaten van opmerkingen van tevoren.

4. Omgaan met buggy fouten

We kunnen niet allemaal uren achter de computer zitten om code te schrijven. Ik veronderstel dat we het kunnen proberen, maar op een gegeven moment moeten we slapen! U zult waarschijnlijk voor de dag moeten afwijken van uw code, met enkele functies die nog steeds kapot zijn. In dit scenario is het cruciaal dat jij laat lange, gedetailleerde opmerkingen achter over waar je dingen hebt nagelaten.

Zelfs na een goede nachtrust zult u misschien verbaasd zijn hoe moeilijk het kan zijn om weer in de swing van de codering te komen. Als u bijvoorbeeld een pagina voor het uploaden van afbeeldingen aan het maken bent en deze onvolledig moet laten, u zou commentaar moeten geven over waar je in het proces gebleven was. Worden de afbeeldingen geüpload en opgeslagen in het tijdelijke geheugen? Of misschien worden ze niet eens herkend in het uploadformulier, of worden ze na het uploaden niet correct weergegeven op de pagina.

Foutopsporing is belangrijk om twee belangrijke redenen. Eerst kan je gemakkelijk op te pikken waar je was gebleven en probeer opnieuw opnieuw om het probleem op te lossen. En ten tweede kunt u een onderscheid maken tussen de live productieversie van uw website en de testomgeving. Vergeet niet dat commentaar moet worden gebruikt om leg uit waarom je iets doet, niet precies wat het doet.

Conclusie

Ontwikkeling voor web-apps en software is een bevredigende praktijk, zij het een moeilijke. Als je een van de weinige ontwikkelaars bent die echt bouwsoftware begrijpt, is het belangrijk om te rijpen met je codeervaardigheden. Het is gewoon een goede gewoonte om op de lange termijn beschrijvende opmerkingen achter te laten, en je zult er waarschijnlijk nooit spijt van krijgen!

Als u suggesties hebt om opmerkingen duidelijker te maken, kunt u ons dit laten weten in het onderstaande discussiegebied!