Hoewel comments vooral bedoeld zijn voor developers<\/a>, kan het schrijven van effectieve comments ook helpen bij het maken van uitstekende documentatie voor de gebruikers van je code. Met behulp van documentgenerators zoals Sphinx<\/a> voor Python projecten, kunnen comments in je code content geven voor je documentatie.<\/p>\n Laten we eens kijken onder de motorkap van comments in Python.<\/p>\n Volgens de Python PEP 8 Style Guide<\/a> zijn er verschillende dingen waar je op moet letten bij het schrijven van comments:<\/p>\n In Python wordt een regel aangegeven als comment\u00a0als hij begint met het symbool Inline comments geven korte beschrijvingen van variabelen en eenvoudige bewerkingen en wordt op dezelfde regel geschreven als het code-statement:<\/p>\n De comment legt de functie van de code uit in hetzelfde statement als de code.<\/p>\n Blokcomments worden gebruikt om complexe logica in de code te beschrijven. Blokcomments in Python zijn vergelijkbaar met inlinecomments – het enige verschil is dat blokcomments op een aparte regel worden geschreven:<\/p>\n Let op dat bij gebruik van blokcomments de comments worden geschreven boven de code die het uitlegt. De Python PEP8 Style Guide schrijft voor dat een regel code niet meer dan negenenzeventig tekens mag bevatten, en inlinecomments gaan vaak over deze lengte heen. Daarom worden blokcomments geschreven om de code op aparte regels te beschrijven.<\/p>\n Python ondersteunt van zichzelf geen comments van meerdere regels, wat betekent dat er geen speciale voorziening is om ze te defini\u00ebren. Desondanks worden vaak comments gebruikt die meerdere regels beslaan.<\/p>\n Je kunt een meerregelig comment maken van meerdere eenregelige comments door elke regel vooraf te laten gaan door Je kunt ook de syntaxis van meerregelige strings gebruiken. In Python kun je meerregelige strings defini\u00ebren door ze in te sluiten tussen In bovenstaande code wordt de meerregelige string niet toegewezen aan een variabele, waardoor de string werkt als een comments. Tijdens runtime negeert Python de string, en hij wordt niet opgenomen in de bytecode. Uitvoering van bovenstaande code levert de volgende uitvoer op:<\/p>\n Naast het leesbaar maken van je code, dienen comments ook enkele speciale doelen in Python, zoals het plannen van toekomstige toevoegingen aan de code en het genereren van documentatie.<\/p>\n In Python zijn docstrings meerregelig comments die uitleggen hoe een bepaalde functie of klasse gebruikt moet worden. De documentatie van je code wordt verbeterd door het maken van hoogwaardige docstrings. Tijdens het werken met een functie of klasse en het gebruik van de ingebouwde functie Python PEP 257<\/a> biedt een standaardmethode voor het declareren van docstrings in Python, zoals hieronder weergegeven:<\/p>\n In de code hierboven geeft de docstring details over hoe de bijbehorende functie werkt. Met documentatiegenerators als Sphinx kan deze docstring gebruikt worden om gebruikers van je project een overzicht te geven van het gebruik van deze methode.<\/p>\n Een docstring die net onder de functie of klassensignature is gedefinieerd, kan ook worden teruggegeven door de ingebouwde functie De functiecall Het Bij het schrijven van code zijn er momenten waarop je bepaalde regels of hele blokken wilt verbeteren. Deze taken worden gemarkeerd door TODO comments. TODO comments komen van pas als je updates of wijzigingen van je code plant, of als je de gebruikers of medewerkers van het project wilt laten weten dat specifieke delen van de code van het bestand nog geschreven moeten worden.<\/p>\n TODO comments\u00a0moeten niet geschreven worden als pseudocode – ze hoeven alleen maar kort de functie van de nog niet geschreven code uit te leggen.<\/p>\n TODO comments en eenregelige blokcomments lijken erg op elkaar, en het enige onderscheid tussen beide is dat TODO comments moeten beginnen met een TODO prefix:<\/p>\n Het is belangrijk op te merken dat, hoewel veel IDE’s deze comments kunnen markeren voor de programmeur, de Python interpreter TODO comments niet anders bekijkt dan blokcomments.<\/p>\n Er zijn een aantal best practices die gevolgd moeten worden bij het schrijven van comments om betrouwbaarheid en kwaliteit te garanderen. Hieronder volgen enkele tips voor het schrijven van kwalitatief goede comments in Python.<\/p>\n Comments die overduidelijk zijn, hebben geen toegevoegde waarde voor je code en moet worden vermeden. Bijvoorbeeld:<\/p>\n Die comment is niet nuttig, omdat het eenvoudigweg zegt wat de code doet zonder uit te leggen waarom het gedaan moet worden. Comments moeten eerder het “waarom” uitleggen dan het “wat” van de code die het beschrijft.<\/p>\n Beter herschreven zou het bovenstaande voorbeeld er zo uit kunnen zien:<\/p>\n Houd je comments kort en gemakkelijk te begrijpen. Ze moeten geschreven zijn in standaard proza, niet in pseudocode, en moeten de noodzaak vervangen om de eigenlijke code te lezen om een algemeen overzicht te krijgen van wat het doet. Te veel details of ingewikkeld comments maken het werk van een programmeur niet eenvoudiger. Bijvoorbeeld:<\/p>\n De comment hierboven geeft meer informatie dan nodig is voor de lezer. In plaats van de logica te specificeren, zouden comments een algemene samenvatting van de code moeten geven. Deze comment kan herschreven worden als:<\/p>\n Identifiers moeten zorgvuldig gebruikt worden in comments. Het veranderen van namen of gevallen van identifiers kan de lezer in verwarring brengen. Voorbeeld:<\/p>\n De bovenstaande comment noemt Als je code schrijft, wil je je houden aan het DRY (don’t repeat yourself) principe en WET (write everything twice) vermijden.<\/p>\n Dit geldt ook voor comments. Vermijd het gebruik van meerdere declarations om je code te beschrijven, en probeer comments die dezelfde code uitleggen samen te voegen tot \u00e9\u00e9n comment. Het is echter belangrijk om voorzichtig te zijn met het samenvoegen van comments: onzorgvuldig samenvoegen van meerdere comments kan resulteren in \u00e9\u00e9n enorme comment die in strijd is met de stijlgidsen en moeilijk te volgen is voor de lezer.<\/p>\n Onthoud dat comments de leestijd van de code moeten verkorten.<\/p>\n In bovenstaande code is de comment onnodig gefragmenteerd, en kan het worden samengevoegd tot \u00e9\u00e9n comment:<\/p>\n Zorg ervoor dat comments op hetzelfde niveau inspringen als de code die het beschrijft. Als dat niet het geval is, kunnen ze moeilijk te volgen zijn.<\/p>\n Deze comment is bijvoorbeeld niet goed ingesprongen of gepositioneerd:<\/p>\n Het kan als volgt herschreven worden:<\/p>\n Comments zijn een belangrijk onderdeel van het schrijven van begrijpelijke code. De investering die je doet in het schrijven van comments is er een die je toekomstige zelf – of andere developers die aan je codebase moeten werken – zullen waarderen. Met comments kun je ook dieper inzicht krijgen in je code.<\/p>\n In deze tutorial heb je meer geleerd over comments in Python, inclusief de verschillende soorten Python comments, wanneer je elk van hen moet gebruiken, en de best practices om te volgen bij het maken ervan.<\/p>\n Het schrijven van goede comments is een vaardigheid die bestudeerd en ontwikkeld moet worden. Om het schrijven van comments te oefenen, kun je overwegen terug te gaan en comments toe te voegen aan enkele van je eerdere projecten. Kijk voor inspiratie en om de best practices in actie te zien naar goed gedocumenteerde Python projecten op GitHub.<\/p>\n Als je klaar bent om je eigen Python projecten live te zetten, kan Kinsta’s Applicatie Hosting<\/a> platform je code in enkele seconden van GitHub naar de cloud<\/a> brengen.<\/p>\n","protected":false},"excerpt":{"rendered":" Comments zijn notities die programmeurs aan hun code toevoegen om uit te leggen wat die code moet doen. De compilers of interpretators die code omzetten in …<\/p>\n","protected":false},"author":275,"featured_media":49455,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_kinsta_gated_content":false,"_kinsta_gated_content_redirect":"","footnotes":""},"tags":[],"topic":[870],"class_list":["post-49226","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","topic-python"],"yoast_head":"\nComments in Python<\/h2>\n
\n
#<\/code>. Wanneer de Python interpreter #<\/code> tegenkomt in je code, negeert hij alles wat na dat symbool komt en produceert hij geen fout. Er zijn twee manieren om comments van \u00e9\u00e9n regel te declaren: inlinecomments en blokcomments.<\/p>\nInlinecomments<\/h3>\n
border = x + 10 # Make offset of 10px<\/code><\/pre>\nBlokcomments<\/h3>\n
import csv\nfrom itertools import groupby\n\n# Get a list of names in a sequence from the csv file\nwith open('new-top-firstNames.csv') as f:\n file_csv = csv.reader(f)\n\n# Skip the header part: (sr, name, perc)\nheader = next(file_csv)\n \n# Only name from (number, name, perc)\npersons = [ x[1] for x in file_csv]\n\n# Sort the list by first letter because \n# The groupby function looks for sequential data.\npersons.sort(key=lambda x:x[0])\ndata = groupby(persons, key=lambda x:x[0])\n\n# Get every name as a list \ndata_grouped = {}\nfor k, v in data:\n # Get data in the form \n # {'A' : [\"Anthony\", \"Alex\"], \"B\" : [\"Benjamin\"]}\n data_grouped[k] = list(v)<\/code><\/pre>\nComments van meerdere regels<\/h3>\n
#<\/code>:<\/p>\n# interpreter \n# ignores\n# these lines<\/code><\/pre>\n\"\"\"<\/code>, drie dubbele aanhalingstekens, of '''<\/code>, drie enkele aanhalingstekens:<\/p>\nprint(\"Multi-Line Comment\")\n\"\"\"\nThis\nString is \nMulti line \n\"\"\"<\/code><\/pre>\nMulti-Line Comment<\/code><\/pre>\n\nSpeciale comments<\/h2>\n
Python Docstring comments<\/h3>\n
help(obj)<\/code>, kunnen docstrings behulpzaam zijn bij het geven van een overzicht van het object.<\/p>\nfrom collections import namedtuple\nPerson = namedtuple('Person', ['name', 'age'])\n\n def get_person(name, age, d=False):\n \"\"\"\nReturns a namedtuple(\"name\", \"age\") object.\nAlso returns dict('name', 'age') if arg `d` is True\n\nArguments:\nname \u2013 first name, must be string\nage \u2013 age of person, must be int\nd \u2013 to return Person as `dict` (default=False)\n\n\"\"\"\np = Person(name, age)\nif d:\n return p._asdict()\nreturn p<\/code><\/pre>\nhelp()<\/code> te gebruiken. De functie help()<\/code> neemt een object of functienaam als argument, en geeft de docstrings van de functie terug als uitvoer. In het bovenstaande voorbeeld kan help(get_person)<\/code> worden aangeroepen om de docstrings van de functie get_person<\/code> te tonen. Als je bovenstaande code uitvoert in een interactieve shell met de vlag -i<\/code>, kun je zien hoe deze docstring door Python wordt geparseerd. Voer de bovenstaande code uit door te typen python -i file.py<\/code>.<\/p>\n![\"Screenshot:](\"https:\/\/kinsta.com\/wp-content\/uploads\/2022\/12\/parsing-python-docstrings-on-command-line.png\")
help(get_person)<\/code> geeft een docstring voor je functie terug. De output bevat get_person(name, age, d=False)<\/code>, wat een functiesignatuur is die Python automatisch toevoegt.<\/p>\nget_person.__ doc__<\/code> attribuut kan ook gebruikt worden om docstrings programmatisch op te vragen en te wijzigen. Na het toevoegen van “Some more new information” in het bovenstaande voorbeeld, verschijnt het in de tweede aanroep van help(get_person)<\/code>. Toch is het onwaarschijnlijk dat je op deze manier dynamisch docstrings tijdens runtime moet wijzigen. <\/p>\nTODO comments<\/h3>\n
# TODO Get serialized data from the CSV file\n# TODO Perform calculations on the data\n# TODO Return to the user<\/code><\/pre>\nBest practices bij het schrijven van Python comments<\/h2>\n
Vermijd het voor de hand liggende<\/h3>\n
x = x + 4 # increase x by 4<\/code><\/pre>\nx = x + 4 # increase the border width<\/code><\/pre>\nHoud Python comments kort en krachtig<\/h3>\n
# return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r)\ndef get_area(r,h):\n return (2*3.14*r*h) + (2*3.14*r*r)<\/code><\/pre>\n# return area of cylinder\ndef get_area(r,h):\n return (2*3.14*r*h) + (2*3.14*r*r)<\/code><\/pre>\nGebruik identifiers zorgvuldig<\/h3>\n
# return class() after modifying argument\ndef func(cls, arg):\n return cls(arg+5)\n<\/code><\/pre>\nclass<\/code> en argument<\/code>, die geen van beide in de code voorkomen. Deze comment kan worden herschreven als:<\/p>\n# return cls() after modifying arg\ndef func(cls, arg):\n return cls(arg+5)<\/code><\/pre>\nDRY en WET<\/h3>\n
\"># function to do x work\ndef do_something(y):\n # x work cannot be done if y is greater than max_limit\n if y < 400:\n print('doing x work')<\/code><\/pre>\n\"># function to do x if arg:y is less than max_limit\ndef do_something(y):\n if y in range(400):\n print('doing x work')<\/code><\/pre>\n<\/code><\/p>\nConsistent inspringen<\/h3>\n
for i in range(2,20, 2):\n# only even numbers\n if verify(i):\n# i should be verified by verify()\n perform(x)<\/code><\/pre>\n# only even numbers\nfor i in range(2,20, 2):\n # i should be verified by verify()\n if verify(i):\n perform(x)<\/code><\/pre>\n\nSamenvatting<\/h2>\n