Följ dessa kodningsstandarder när du skriver kod som ska inkluderas i Django.
\npre-commit är ett ramverk för att hantera pre-commit hooks. Dessa hooks hjälper till att identifiera enkla problem innan koden skickas för granskning. Genom att kontrollera dessa problem före kodgranskningen kan granskaren fokusera på själva ändringen, och det kan också bidra till att minska antalet CI-körningar.
\nFör att använda verktyget måste du först installera pre-commit och sedan git-hooks:
Linux / macOS
$ python -m pip install pre-commit\n$ pre-commit install\nWindows
...\\> py -m pip install pre-commit\n...\\> pre-commit install\nVid det första åtagandet kommer pre-commit att installera hooks, dessa installeras i sina egna miljöer och tar en kort stund att installera vid första körningen. Efterföljande kontroller kommer att vara betydligt snabbare. Om ett fel hittas kommer ett lämpligt felmeddelande att visas. Om felet gällde black eller isort kommer verktyget att gå vidare och åtgärda dem åt dig. Granska ändringarna och lägg upp dem på nytt för commit om du är nöjd med dem.
Alla filer bör formateras med hjälp av den automatiska formateraren black. Detta kommer att köras av pre-commit om det är konfigurerat.
Projektarkivet innehåller en fil med namnet .editorconfig. Vi rekommenderar att du använder en textredigerare med stöd för EditorConfig för att undvika problem med indragning och blanksteg. Python-filerna använder 4 mellanslag för indragning och HTML-filerna använder 2 mellanslag.
Om inte annat anges, följ PEP 8.
\nAnvänd flake8 för att kontrollera om det finns problem i detta område. Observera att vår .flake8-fil utesluter vissa fel som vi inte anser vara grova överträdelser. Kom ihåg att PEP 8 endast är en riktlinje, så respektera stilen i den omgivande koden som ett primärt mål.
Ett undantag från PEP 8 är våra regler om radlängder. Begränsa inte kodrader till 79 tecken om det innebär att koden ser betydligt fulare ut eller är svårare att läsa. Vi tillåter upp till 88 tecken eftersom detta är den radlängd som används av black. Denna kontroll ingår när du kör flake8. Dokumentation, kommentarer och docstrings bör vara omslutna av 79 tecken, även om PEP 8 föreslår 72.
Interpolering av strängvariabler kan använda %-formatting, f-strings, eller str.format() på lämpligt sätt, med målet att maximera kodens läsbarhet.
Slutliga bedömningar av läsbarheten lämnas till Merger’s diskretion. Som en vägledning bör f-strängar endast använda vanlig variabel- och egenskapsåtkomst, med föregående lokal variabeltilldelning för mer komplexa fall:
\n# Allowed\nf"hello {user}"\nf"hello {user.name}"\nf"hello {self.user.name}"\n\n# Disallowed\nf"hello {get_user()}"\nf"you are {user.age * 365.25} days old"\n\n# Allowed with local variable assignment\nuser = get_user()\nf"hello {user}"\nuser_days_old = user.age * 365.25\nf"you are {user_days_old} days old"\nf-strings bör inte användas för strängar som kan behöva översättas, t.ex. fel- och loggmeddelanden. I allmänhet är format() mer omständlig, så de andra formateringsmetoderna är att föredra.
Slösa inte tid på att göra en orelaterad refaktorisering av befintlig kod för att justera formateringsmetoden.
\nUndvik att använda ”vi” i kommentarer, t.ex. ”Loop over” i stället för ”We loop over”.
Använd understrykningstecken, inte camelCase, för variabel-, funktions- och metodnamn (t.ex. poll.get_unique_voters(), inte poll.getUniqueVoters()).
Använd InitialCaps för klassnamn (eller för fabriksfunktioner som returnerar klasser).
I dokumentationer, följ stilen för befintliga dokumentationer och PEP 257.
I tester, använd assertRaisesMessage() och assertWarnsMessage() istället för assertRaises() och assertWarns() så att du kan kontrollera undantaget eller varningsmeddelandet. Använd assertRaisesRegex() och assertWarnsRegex() endast om du behöver matchning med reguljära uttryck.
Använd assertIs(..., True/False) för att testa booleska värden, snarare än assertTrue() och assertFalse(), så att du kan kontrollera det faktiska booleska värdet, inte sanningshalten i uttrycket.
I testdokumentationer ska du ange det förväntade beteende som varje test demonstrerar. Inkludera inte ingresser som ”Testar att” eller ”Säkerställer att”.
\nReservera ärendehänvisningar för obskyra frågor där ärendet innehåller ytterligare detaljer som inte enkelt kan beskrivas i dokument eller kommentarer. Inkludera ärendenumret i slutet av en mening så här:
\ndef test_foo():\n """\n A test docstring looks like this (#123456).\n """\n ...\nDär det är tillämpligt, använd uppackningsgeneraliseringar som överensstämmer med PEP 448, till exempel sammanslagning av mappningar ({**x, **y}) eller sekvenser ([*a, *b]). Detta förbättrar prestanda, läsbarhet och underhållsmässighet samtidigt som det minskar antalet fel.
Använd isort för att automatisera importsorteringen enligt riktlinjerna nedan.
\nSnabb start:
\nLinux / macOS
$ python -m pip install "isort >= 7.0.0"\n$ isort .\nWindows
...\\> py -m pip install "isort >= 7.0.0"\n...\\> isort .\nDetta kör isort rekursivt från din aktuella katalog och ändrar alla filer som inte överensstämmer med riktlinjerna. Om du behöver ha import i fel ordning (för att undvika cirkulär import, till exempel), använd en kommentar som denna:
import module # isort:skip\nLägg import i dessa grupper: future, standardbibliotek, tredjepartsbibliotek, andra Django-komponenter, lokal Django-komponent, try/excepts. Sortera raderna i varje grupp alfabetiskt efter det fullständiga modulnamnet. Placera alla import module-satser före from module import objects i varje avsnitt. Använd absolut import för andra Django-komponenter och relativ import för lokala komponenter.
Alfabetisera artiklarna på varje rad med de versala artiklarna grupperade före de gemena artiklarna.
Bryt långa rader med parenteser och dra in fortsättningsraderna med 4 mellanslag. Sätt ett efterföljande kommatecken efter den sista importen och sätt den avslutande parentesen på en egen rad.
\nAnvänd en blankrad mellan den sista importen och all kod på modulnivå, och använd två blankrader ovanför den första funktionen eller klassen.
\nTill exempel (kommentarerna är endast i förklarande syfte):
\ndjango/contrib/admin/example.py# future\nfrom __future__ import unicode_literals\n\n# standard library\nimport json\nfrom itertools import chain\n\n# third-party\nimport bcrypt\n\n# Django\nfrom django.http import Http404\nfrom django.http.response import (\n Http404,\n HttpResponse,\n HttpResponseNotAllowed,\n StreamingHttpResponse,\n cookie,\n)\n\n# local Django\nfrom .models import LogEntry\n\n# try/except\ntry:\n import yaml\nexcept ImportError:\n yaml = None\n\nCONSTANT = "foo"\n\n\nclass Example: ...\nAnvänd bekvämlighetsimport när det är möjligt. Gör till exempel så här
\nfrom django.views import View\nistället för:
\nfrom django.views.generic.base import View\nFölj nedanstående regler i Django mallkod.
\n{% extends %} bör vara den första raden utan kommentar.
Gör så här:
\n{% extends "base.html" %}\n\n{% block content %}\n <h1 class="font-semibold text-xl">\n {{ pages.title }}\n </h1>\n{% endblock content %}\nEller det här:
\n{# This is a comment #}\n{% extends "base.html" %}\n\n{% block content %}\n <h1 class="font-semibold text-xl">\n {{ pages.title }}\n </h1>\n{% endblock content %}\nGör inte så här:
\n{% load i18n %}\n{% extends "base.html" %}\n\n{% block content %}\n <h1 class="font-semibold text-xl">\n {{ pages.title }}\n </h1>\n{% endblock content %}\nLägg till exakt ett mellanslag mellan {{, variabelinnehåll och }}.
Gör så här:
\n{{ user }}\nGör inte så här:
\n{{user}}\nI {% load ... %}, lista bibliotek i alfabetisk ordning.
Gör så här:
\n{% load i18n l10 tz %}\nGör inte så här:
\n{% load l10 i18n tz %}\nLägg till exakt ett mellanslag mellan {%, taggens innehåll och %}.
Gör så här:
\n{% load humanize %}\nGör inte så här:
\n{%load humanize%}\nLägg till taggnamnet {% block %} i taggen {% endblock %} om den inte står på samma rad.
Gör så här:
\n{% block header %}\n\n Code goes here\n\n{% endblock header %}\nGör inte så här:
\n{% block header %}\n\n Code goes here\n\n{% endblock %}\nInom hakparenteser separeras tokens med enkla mellanslag, utom runt . för attributåtkomst och | för ett filter.
Gör så här:
\n{% if user.name|lower == "admin" %}\nGör inte så här:
\n{% if user . name | lower == "admin" %}\n\n{{ user.name | upper }}\nInom en mall som använder {% extends %}, undvik indragning av toppnivå {% block %} taggar.
Gör så här:
\n{% extends "base.html" %}\n\n{% block content %}\nGör inte så här:
\n{% extends "base.html" %}\n\n {% block content %}\n ...\nI Django-vyer ska den första parametern i en vyfunktion heta request.
Gör så här:
\ndef my_view(request, foo): ...\nGör inte så här:
\ndef my_view(req, foo): ...\nFältnamn ska vara gemener och underscores ska användas i stället för camelCase.
\nGör så här:
\nclass Person(models.Model):\n first_name = models.CharField(max_length=20)\n last_name = models.CharField(max_length=40)\nGör inte så här:
\nclass Person(models.Model):\n FirstName = models.CharField(max_length=20)\n Last_Name = models.CharField(max_length=40)\nKlass Meta bör visas efter att fälten har definierats, med en enda blankrad som skiljer fälten och klassdefinitionen åt.
\nGör så här:
\nclass Person(models.Model):\n first_name = models.CharField(max_length=20)\n last_name = models.CharField(max_length=40)\n\n class Meta:\n verbose_name_plural = "people"\nGör inte så här:
\nclass Person(models.Model):\n class Meta:\n verbose_name_plural = "people"\n\n first_name = models.CharField(max_length=20)\n last_name = models.CharField(max_length=40)\nOrdningsföljden för modellens inre klasser och standardmetoder bör vara enligt följande (observera att alla inte är obligatoriska):
\nAlla databasfält
Anpassade chefsattribut
klass Meta
def __str__() och andra magiska Python-metoder
def save()
def get_absolute_url()
Eventuella anpassade metoder
Om val definieras för ett visst modellfält, definieras varje val som en mappning, med ett namn i versaler som ett klassattribut på modellen. Exempel:
class MyModel(models.Model):\n DIRECTION_UP = "U"\n DIRECTION_DOWN = "D"\n DIRECTION_CHOICES = {\n DIRECTION_UP: "Up",\n DIRECTION_DOWN: "Down",\n }\nAlternativt kan du överväga att använda Uppräkningstyper:
\nclass MyModel(models.Model):\n class Direction(models.TextChoices):\n UP = "U", "Up"\n DOWN = "D", "Down"\ndjango.conf.settingsLink to this heading#Moduler bör i allmänhet inte använda inställningar som lagras i django.conf.settings på toppnivå (dvs. utvärderas när modulen importeras). Förklaringen till detta är som följer:
Manuell konfiguration av inställningar (dvs. utan att förlita sig på miljövariabeln DJANGO_SETTINGS_MODULE) är tillåten och möjlig enligt följande:
from django.conf import settings\n\nsettings.configure({}, SOME_SETTING="foo")\nMen om någon inställning används före raden settings.configure fungerar inte detta. (Internt är settings ett LazyObject som konfigurerar sig själv automatiskt när inställningarna öppnas om det inte redan har konfigurerats).
Så om det finns en modul som innehåller kod enligt följande:
\nfrom django.conf import settings\nfrom django.urls import get_callable\n\ndefault_foo_view = get_callable(settings.FOO_VIEW)\n…så kommer import av denna modul att leda till att inställningsobjektet konfigureras. Det innebär att möjligheten för tredje part att importera modulen på högsta nivå är oförenlig med möjligheten att konfigurera inställningsobjektet manuellt, eller gör det mycket svårt under vissa omständigheter.
\nIstället för ovanstående kod måste en nivå av lathet eller indirektion användas, till exempel django.utils.functional.LazyObject, django.utils.functional.lazy() eller lambda.
Markera alla strängar för internationalisering; se i18n-dokumentation för mer information.
Ta bort import-satser som inte längre används när du ändrar kod. flake8 kommer att identifiera dessa importer åt dig. Om en oanvänd import måste finnas kvar för bakåtkompatibilitet, markera slutet av med # NOQA för att tysta flake8-varningen.
Ta systematiskt bort alla efterföljande blanksteg från din kod eftersom de lägger till onödiga byte, lägger till visuell röra i patcherna och ibland också kan orsaka onödiga sammanfogningskonflikter. Vissa IDE:er kan konfigureras så att de automatiskt tar bort dem och de flesta VCS-verktyg kan ställas in så att de markerar dem i diff-utdata.
Skriv inte ditt namn i den kod du bidrar med. Vår policy är att hålla bidragsgivarnas namn i filen AUTHORS som distribueras med Django - inte utspridda i själva kodbasen. Inkludera gärna en ändring av filen AUTHORS i din patch om du gör mer än en enda trivial ändring.
För detaljer om den JavaScript-kodstil som används av Django, se JavaScript-kod.
\n