Broncode Commentaar Styling: tips en praktische tips

Ontwikkelaars die zich altijd hebben beziggehouden met grote projecten begrijpen het belang van opmerkingen over codes. Wanneer u veel functies in dezelfde toepassing bouwt, wordt de situatie vaak gecompliceerd. Er zijn zoveel databits inclusief functies, variabele referenties, retourwaarden, parameters ... hoe wordt verwacht dat u bijhoudt?

Het is geen verrassing dat het belangrijk is om commentaar te leveren op je code, zowel voor solo- als voor teamprojecten. Maar veel ontwikkelaars weten niet hoe ze dit proces moeten aanpakken. Ik heb een aantal van mijn eigen persoonlijke trucjes geschetst om nette, opgemaakte code-opmerkingen te maken . Standaarden en reactiesjablonen variëren per ontwikkelaar - maar uiteindelijk moet je streven naar schone en leesbare opmerkingen om verwarrende gebieden in je 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 richtlijnen zijn voor 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 te formatteren. Ik zal een paar reguliere stijlen aanbieden en gedetailleerd ingaan op hun doel.

Inline commentaar

Vrijwel elke programmeertaal biedt inline commentaar . 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 in te loggen om mogelijk verwarrende functionaliteit te verklaren . 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, want over het algemeen hoef je geen enkele regel opmerkingen helemaal onderaan je pagina te zien, maar vooral voor verwarrende kruispunten in je code zijn deze veel lastiger om te laten vallen op het laatste moment.

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 worden vooral gezien rond functies en bibliotheekbestanden. Wanneer u een nieuwe functie instelt, is het een goede gewoonte om een beschrijvend blok boven de declaratie toe te voegen .

 / ** * @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 waarschijnlijk een functie geschreven in JavaScript, modalPopup genaamd , die een enkele parameter nodig heeft. 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 sleutel. Deze zullen je code op geen enkele manier beïnvloeden, dus je zou @description kunnen schrijven @description plaats van @desc zonder enige verandering.

Deze kleine sleutels worden in feite commentaartags genoemd die zwaar op de website zijn gedocumenteerd. 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 alles in beweging te houden, zodat ik belangrijke informatie in één oogopslag kan bekijken . Je zou ook moeten opmerken dat ik de commentaartekst van de /* */ blokstijl heb gebruikt. Hierdoor blijft alles veel schoner dan het toevoegen van een dubbele schuine streep vanaf elke regel.

Groeps- / klas-opmerkingen

Afgezien van opmerkingen over functies en loops, worden blokgebieden niet zo vaak gebruikt. Waar u echt sterke block-opmerkingen nodig hebt, staat aan het begin 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 dit in veel CMS, zoals WordPress, zien.

Het bovenste gedeelte van uw pagina moet opmerkingen bevatten over het bestand zelf. Op deze manier kunt u snel controleren waar u 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 uit de klas nodig hebt.

 / ** * @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 {} 

U 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.

De tag @required is niet iets dat ik ergens anders heb gezien. Ik heb het formaat in een paar 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 hoofdklasse is een goede manier om te onthouden welke bestanden nodig zijn .

Front-end code commentaar

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

(Afbeeldingsbron: Fotolia)

JavaScript volgt een meer traditionele methode van commentaar vergelijkbaar met Java, PHP en C / C ++. CSS maakt alleen gebruik van de blokachtige opmerkingen die worden aangegeven door een schuine streep en een sterretje . Onthou 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 kunnen gebruiken.

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 te verklaren. 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 wat ik groepeer creëer gemaakt 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, vulling, lettertypen, kleuren, etc.
• @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 gemerkt dat het tagging-systeem veel kan helpen. In tegenstelling tot PHP of JavaScript, gebruik ik een enkele tag @group gevolgd door een categorie of trefwoorden. Ik heb hieronder twee voorbeelden opgenomen, zodat je een idee krijgt van wat ik bedoel.

 / ** @group footer * / #footer {styles ...} 

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

U kunt ook een beetje extra detail in elk commentaarblok toevoegen. Ik kies ervoor om dingen eenvoudig en duidelijk te houden, zodat de stylesheets gemakkelijk kunnen worden afgeroomd. 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 als ontwikkelaars dat we reacties schrijven die mensen kunnen 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 ​​onderzoeksdocument op universiteitsniveau te schrijven, maar gewoon tips achter te laten !

 functie getTheMail () {// code hier zal e-mail / * run code bouwen als onze aangepaste functie sendMyMail () functioneert, retourneert true find sendMyMail () 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 slechts een paar woorden zijn beter dan niets . Wanneer je in de toekomst weer projecten gaat bewerken en bewerken, is het vaak verrassend hoeveel je 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 kun je nooit teveel reacties achterlaten ! Maar je kunt te veel slechte opmerkingen achterlaten.

Neem als algemene vuistregel enige tijd om te pauzeren en na te denken voordat je gaat schrijven . Stel jezelf de vraag wat het meest verwarrend is voor het programma en hoe kun je het het beste uitleggen in "dummy" 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 u helpt de functionaliteit gemakkelijker te onthouden.

2. Verlicht wat ruimte!

Ik kan niet genoeg benadrukken hoe belangrijk witruimte kan zijn. Dit geldt dubbel voor ontwikkelaars van PHP en Ruby 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, springt deze stijl van commentaar duidelijk naar voren . Het maakt het vinden van fouten en het honderden malen eenvoudiger corrigeren van uw code als variabele blokken zo schoon zijn .

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 een grote blokkeringsreactie toe te voegen 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-navigatie van het submenu. De eerste opmerking is inline om uit te leggen waarom we alle .sub klassen verbergen. Boven de live klikgebeurtenishandler heb ik een blokcommentaar gebruikt en al het schrijven op hetzelfde punt ingesprongen . 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 afstand is dit misschien wel een van de beste gewoonten om erin te komen. 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.

(Afbeeldingsbron: Fotolia)

Maar als je de opmerkingen kunt schrijven terwijl je codeert , zal alles nog vers in je geheugen zitten . Meestal blijven ontwikkelaars vastzitten aan een probleem en doorzoeken het web naar de eenvoudigste 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 beste moment zijn 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 benodigde hoeveelheid tijd om terug te gaan en uit te zoeken 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! Waarschijnlijk zul je de weg moeten delen met je code voor de dag met een aantal functies die nog steeds kapot zijn. In dit scenario is het van cruciaal belang dat je lange, gedetailleerde opmerkingen achterlaat over waar je dingen hebt achtergelaten .

(Afbeeldingsbron: Fotolia)

Zelfs na een frisse 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, moet u reageren waar u 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 kun je gemakkelijk verdergaan waar je was gebleven en opnieuw proberen of je het probleem (de problemen) oplost . En ten tweede kunt u onderscheid maken tussen de live productieversie van uw website en de testomgeving . Onthoud dat opmerkingen moeten worden gebruikt om uit te leggen waarom u 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. Beschrijvende opmerkingen achterlaten is gewoon een goede gewoonte op de lange termijn, en je zult er waarschijnlijk nooit spijt van krijgen!

Als je suggesties hebt voor duidelijker commentaar, laat het ons weten in het onderstaande discussiegebied!

AI-Powered Amazon Music Unlimited Rolls Out

Toepassingen zoals Spotify en Apple Music bieden miljoenen nummers voor audiofielen en worden nu geconfronteerd met een nieuwe on-demand streaming-concurrentie van Amazon .Amazon Music Unlimited is een aanvulling op de huidige Amazon Prime Music bij het bedienen van luisteraars met 'tientallen miljoenen' nummers die te vinden zijn in de muziekbibliotheek van Amazon

(Technische en ontwerptips)

Auto-Genereer mooie kleurenpaletten met Ambiance

Of u nu een UI / UX-ontwerper of een digitale kunstenaar bent, u moet weten dat kleur cruciaal is voor het eindproduct .Maar het vinden van het juiste kleurenschema is moeilijk en het gaat meestal gepaard met veel vallen en opstaan. Met Ambiance kunt u kleurenschema's automatisch vanuit de COLOURlovers-API genereren, alles met één klik!D

(Technische en ontwerptips)