Lean na caighdeáin códaithe seo le do thoil agus cód á scríobh agat le cur san áireamh in Django.
\nIs creat é `réamh-choimite`_ chun crúca< https://pre-commit.com> í réamhthiomanta a bhainistiú. Cuidíonn na crúcaí seo le saincheisteanna simplí a aithint sula ndéanann siad cód le haghaidh Trí na saincheisteanna seo a sheiceáil roimh athbhreithniú ar chód tugann sé deis don athbhreithneoir díriú ar an athrú féin, agus féadfaidh sé cabhrú freisin le líon na rith CI a laghdú.
\nChun an uirlis a úsáid, suiteáil pre-chommit ar dtús agus ansin na crúcaí git:
Linux / macOS
$ python -m pip install pre-commit\n$ pre-commit install\nWindows
...\\> py -m pip install pre-commit\n...\\> pre-commit install\nAr an gcéad tiomantas suiteálfaidh réamh-choimite na crúcaí, suiteáiltear iad seo ina dtimpeallachtaí féin agus tógfaidh siad tamall gairid iad a shuiteáil ar an gcéad rith. Beidh seiceálacha ina dhiaidh sin i bhfad níos tapa Má aimsítear earráid taispeánfar teachtaireacht earráide iomchuí. Má bhí an earráid le dub nó isort ansin rachaidh an uirlis ar aghaidh agus iad a shocrú duit. Déan athbhreithniú ar na hathruithe agus déan athchéim a dhéanamh le tiomantas má tá tú sásta leo.
Ba chóir gach comhad a fhormáidiú ag baint úsáide as an uath-fhormáiditheoir: pypi: black. Reáchtálfaidh réamh-chommit é seo má tá sé sin cumraithe.
Cuimsíonn stór an tionscadail comhad .editorconfig. Molaimid eagarthóir téacs a úsáid le tacaíocht EditorConfig chun saincheisteanna insint agus spás bán a sheachaint. Úsáideann na comhaid Python 4 spás le haghaidh ionchur agus úsáideann na comhaid HTML 2 spás.
Mura sonraítear a mhalairt, lean: pep: 8.
\nUse flake8 to check for problems in this area. Note that our\n.flake8 file excludes some errors that we don't consider as gross\nviolations. Remember that PEP 8 is only a guide, so respect the style of\nthe surrounding code as a primary goal.
Eisceacht to:pep: 8 is iad ár rialacha maidir le fad líne. Ná teorainn le línte cód go 79 carachtar má chiallaíonn sé go bhfuil cuma níos gránna ar an gcód nó go bhfuil sé níos deacra é a léamh. Ceadaímid suas le 88 carachtar mar is é seo an fad líne a úsáideann dub`. Cuirtear an seiceáil seo san áireamh nuair a ritheann tú ``flake8. Ba chóir doiciméadú, tráchtanna, agus docstrings a fhilleadh ag 79 carachtar, fiú cé go molann: pep: 8 72.
Féadfaidh idirphóireacht athraitheach teaghrána:py:ref: %-formáidiú `, :py:ref: <old-string-formatting>f-strings , nó:py:meth: `str.format mar is cuí, leis an aidhm léiteacht cód a uasmh <f-strings>éadú.
\nFágtar breithiúnais dheiridh ar inléiteacht faoi rogha an Cumaisc. Mar threoir, níor cheart go n-úsáidfeadh f-teaghráin ach rochtain shimplí athróg agus réadmhaoin, le sannadh athróg áitiúil roimhe seo le haghaidh cásanna níos casta:
\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"\nníor cheart f-teaghráin a úsáid le haghaidh teaghrán ar bith a bhféadfadh aistriúchán a bheith ag teastáil uaidh, lena n-áirítear teachtaireachtaí earráide agus logáil. Go ginearálta bíonn formáid() níos briathartha, mar sin is fearr na modhanna formáidithe eile.
Ná cuir am amú ag déanamh athfhachtóirí neamhghaolmhara ar an gcód atá ann cheana chun an modh formáidithe a choigeartú.
\nSeachain úsáid “muid” i dtráchtanna, m.sh. “Lúb thar” seachas “Táimid lúb thart”.
Úsáid béim, ní CamelCase, le haghaidh ainmneacha athróg, feidhm agus modh (ie poll.get_unique_votes () ``, ní ``poll.getUniqueVoters ()).
Úsáid InitialCaps le haghaidh ainmneacha ranga (nó le haghaidh feidhmeanna monarcha a thugann ranganna ar ais).
I docstrings, lean stíl na docstrings atá ann cheana agus: pep: 257.
I dtástálacha, bain úsáid ai:meth: ~django.test.simpletestcase.assertRaisesMessage agus:meth: ~django.test.simpletestCase.assertWarnsMessage in ionad:meth: ~UnitTest.TestCase.AsserTraises agus:meth: ~UnitTest.TestCase.Asserns ionas gur féidir leat an eisceacht nó teachtaireacht rabhaidh. Úsáid: Meth: ~UnitTest.TestCase.AsserTraisesRegex agus:meth: ~UnitTest.TestCase.AssertWarnsRegex ach amháin má theastaíonn meaitseáil léirithe rialta uait.
\nÚsáid: Meth: Assertis (..., True/False) <unittest.TestCase.assertIs>`chun luachanna boolean a thástáil, seachas: meth: `~UnitTest.TestCase.AssertTrue agus:meth: ~UnitTest.TestCase.assertFalse, ionas gur féidir leat an luach boolean iarbhír a sheiceáil, ní fírinneacht an abairt.
\nI ndocstrings tástála, luaigh an t-iompar a bhfuiltear ag súil leis a léiríonn gach tástáil. Ná cuir réamhshamhlacha mar “Tástálacha sin” nó “Cinntíonn sé sin” san áireamh.
\nTagairtí ticéad a chur in áirithe le haghaidh saincheisteanna doiléire ina bhfuil sonraí breise sa ticéad nach féidir cur síos a dhéanamh orthu go héasca i ndocstrings nó i dtuairimí. Cuir uimhir an ticéad san áireamh ag deireadh abairt mar seo:
\ndef test_foo():\n """\n A test docstring looks like this (#123456).\n """\n ...\nWhere applicable, use unpacking generalizations compliant with PEP 448,\nsuch as merging mappings ({**x, **y}) or sequences ([*a, *b]). This\nimproves performance, readability, and maintainability while reducing errors.
Úsáid isort chun sórtáil iompórtála a uathoibriú ag baint úsáide as na treoirlínte thíos.
\nTús tapa:
\nLinux / macOS
$ python -m pip install "isort >= 7.0.0"\n$ isort .\nWindows
...\\> py -m pip install "isort >= 7.0.0"\n...\\> isort .\nRitheann sé seo isort go athshlánach ó d'eolaire reatha, ag modhnú aon chomhaid nach gcomhlíonann leis na treoirlínte. Más gá duit allmhairí a bheith as ord (chun allmhairiú ciorclach a sheachaint, mar shampla) bain úsáid as trácht mar seo:
import module # isort:skip\nCuir allmhairí sna grúpaí seo: todhchaí, leabharlann chaighdeánach, leabharlanna tríú páirtí, comhpháirteanna Django eile, comhpháirt áitiúil Django, déan iarracht / seachas. Sórtáil na línte i ngach grúpa in ord aibítre de réir ainm iomlán an mhodúil. Cuir gach ráiteas modúil iompórtála roimh ó réada iompórtála modúil i ngach roinn. Bain úsáid as allmhairí absalóideacha le haghaidh comhpháirteanna Django eile agus allmhairí coibhneasta le haghaidh comhpháirteanna áitiúla.
Ar gach líne, déan na míreanna aibítir leis na míreanna uachtarcháis atá grúpáilte roimh na míreanna beaga.
Briseadh línte fada ag baint úsáide as lúibíní agus línte leanúna le 4 spás. Cuir camóg siar san áireamh tar éis an allmhairiú deireanach agus cuir an lúibín deiridh ar a líne féin.
\nÚsáid líne bán amháin idir an t-allmhairiú deireanach agus aon chód leibhéal an mhodúil, agus bain úsáid as dhá líne bán os cionn an chéad fheidhm nó an rang.
\nMar shampla (tá tuairimí chun críocha míniúcháin amháin):
\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: ...\nÚsáid allmhairí áisiúlachta aon uair atá Mar shampla, déan seo:
\nfrom django.views import View\nin ionad:
\nfrom django.views.generic.base import View\nLean na rialacha thíos i gcód teimpléad Django.
\nBa chóir gurb é {% leathnaíonn%} an chéad líne neamh-trácht.
Déan é seo:
\n{% extends "base.html" %}\n\n{% block content %}\n <h1 class="font-semibold text-xl">\n {{ pages.title }}\n </h1>\n{% endblock content %}\nNó seo:
\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 %}\nNá déan é seo:
\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 %}\nCuir spás amháin go díreach idir {{, ábhar athraitheach, agus }}.
Déan é seo:
\n{{ user }}\nNá déan é seo:
\n{{user}}\nI ``{% load...%} `, liostaigh leabharlanna in ord aibítre.
\nDéan é seo:
\n{% load i18n l10 tz %}\nNá déan é seo:
\n{% load l10 i18n tz %}\nCuir spás amháin go díreach idir {%, ábhar clibeanna, agus %}.
Déan é seo:
\n{% load humanize %}\nNá déan é seo:
\n{%load humanize%}\nCuir ainm an chlib {% block%} sa chlib {% endblock%} mura bhfuil sé ar an líne chéanna.
Déan é seo:
\n{% block header %}\n\n Code goes here\n\n{% endblock header %}\nNá déan é seo:
\n{% block header %}\n\n Code goes here\n\n{% endblock %}\nTaobh istigh de bhraiceanna cuartha, comharthaí ar leithligh de réir spásanna aonair, ach amháin timpeall an . le haghaidh rochtana tréithe agus an | le haghaidh scagaire.
Déan é seo:
\n{% if user.name|lower == "admin" %}\nNá déan é seo:
\n{% if user . name | lower == "admin" %}\n\n{{ user.name | upper }}\nLaistigh de theimpléad ag baint úsáide as {% leathnaíonn%}, seachain clibeanna ``{% block%} `a chur isteach.
Déan é seo:
\n{% extends "base.html" %}\n\n{% block content %}\nNá déan é seo:
\n{% extends "base.html" %}\n\n {% block content %}\n ...\nI dtuairimí Django, ba chóir “iarratas” a thabhairt ar an gcéad pharaiméadar i bhfeidhm amharc.
\nDéan seo:
\ndef my_view(request, foo): ...\nNá déan seo:
\ndef my_view(req, foo): ...\nBa chóir go mbeadh ainmneacha réimse le litreacha beaga uile, ag úsáid béim in ionad CamelCase.
\nDéan seo:
\nclass Person(models.Model):\n first_name = models.CharField(max_length=20)\n last_name = models.CharField(max_length=40)\nNá déan seo:
\nclass Person(models.Model):\n FirstName = models.CharField(max_length=20)\n Last_Name = models.CharField(max_length=40)\nBa chóir go mbeadh an aicme Meta` le feiceáil* tar éis * na réimsí a shainiú, le líne bán amháin a scarann na réimsí agus an sainmhíniú ranga.
\nDéan seo:
\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"\nNá déan seo:
\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)\nBa chóir go mbeadh ord ranganna istigh samhail agus modhanna caighdeánacha mar seo a leanas (ag tabhairt faoi deara nach bhfuil siad seo uile ag teastáil):
\n\nMá shainmhínítear “roghanna” do réimse samhail ar leith, sainmhínigh gach rogha mar mhapáil, le ainm uile-uachtaracha mar thréith aicme ar an tsamhail. Sampla:
\nclass MyModel(models.Model):\n DIRECTION_UP = "U"\n DIRECTION_DOWN = "D"\n DIRECTION_CHOICES = {\n DIRECTION_UP: "Up",\n DIRECTION_DOWN: "Down",\n }\nDe rogha air sin, smaoinigh ar úsáid:ref: field-choices-enum-typepes:
\nclass MyModel(models.Model):\n class Direction(models.TextChoices):\n UP = "U", "Up"\n DOWN = "D", "Down"\ndjango.conf.settingsLink to this heading#Níor chóir modúil úsáid go ginearálta socruithe a stóráiltear i django.conf.settings` ag an leibhéal barr (ie meastóireacht nuair a dhéantar an modúl a allmhairiú). Is é seo a leanas an míniú ar seo:
\nCeadaítear cumraíocht láimhe na socruithe (ie gan brath ar an athróg comhshaoil: envvar: DJANGO_SETTINGS_MODULE) agus is féidir mar seo a leanas:
\nfrom django.conf import settings\n\nsettings.configure({}, SOME_SETTING="foo")\nMar sin féin, má dhéantar rochtain ar aon socrú roimh an líne settings.configure, ní oibreoidh sé seo. (Go hinmheánach, is lazyObject é `socruithe ``a chumraíonn é féin go huathoibríoch nuair a bhíonn rochtain ar na socruithe mura bhfuil sé cumraithe cheana féin).
Mar sin, má tá modúl ann ina bhfuil cód éigin mar seo a leanas:
\nfrom django.conf import settings\nfrom django.urls import get_callable\n\ndefault_foo_view = get_callable(settings.FOO_VIEW)\n... ansin beidh an modúl seo a allmhairiú mar thoradh ar an réad socruithe a chumrú. Ciallaíonn sé sin go bhfuil an cumas do thríú páirtithe an modúl a iompórtáil ag an leibhéal barr comhoiriúnach leis an gcumas an réad socruithe a chumrú de láimh, nó go ndéanann sé an-deacair i gcúinsí áirithe.
\nIn ionad an chód thuas, caithfear leibhéal leisce nó intreo a úsáid, mar shampla django.utils.functional.lazyobject, django.utils.functional.lazy () ``nó ``lambda`.
Marcáil na teaghráin go léir le haghaidh idirnáisiúnaithe; féach an doiciméadú: doc: i</topics/i18n/index> 18n le haghaidh sonraí.
Bain ráitis `allmhairi nach n-úsáidtear a thuilleadh nuair a athraíonn tú cód. :pypi: aithneoidh flake8 na hallmhairí seo duit. Más gá allmhairiú neamhúsáidte fanacht le haghaidh comhoiriúnacht ar ais, marcáil deireadh le # NOQA` chun an rabhadh flake8 a thostú.
Bain gach spás bán rianúil ó do chód go córasach de réir mar a chuireann siad sin béite neamhriachtanacha leis, cuireann siad neamhghnách amhairc leis na paistí agus is féidir leo coimhlintí cumaisc gan ghá a chur faoi Is féidir roinnt IDE a chumrú chun iad a bhaint go huathoibríoch agus is féidir an chuid is mó d'uirlisí VCS a shocrú chun aird a tharraingt orthu in aschuir diff.
Ná cuir d'ainm sa chód a chuireann tú le do thoil. Is é ár mbeartas ainmneacha rannpháirtithe a choinneáil sa chomhad ``AUTHORS` a dháiltear le Django - gan scaipthe ar fud an chód-bhunachar féin. Ná bíodh leisce ort athrú ar an gcomhad ``AUTHORS` a chur san áireamh i do phaiste má dhéanann tú níos mó ná athrú tábhachtach amháin.
Le haghaidh sonraí faoin stíl cód JavaScript a úsáideann Django, féach:doc: javascript.
\n