---
title: "Stíl chódú"
version: 5.2
locale: ga
source: https://docs.djangoproject.com/ga/5.2/internals/contributing/writing-code/coding-style/
canonical: https://djangodocs.dev/ga/5.2/internals/contributing/writing-code/coding-style/
---
# Stíl chódú

Lean na caighdeáin códaithe seo le do thoil agus cód á scríobh agat le cur san áireamh in Django.

## Seiceálacha réamhthiomanta

Is creat é  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ú.

Chun an uirlis a úsáid, suiteáil `pre-chommit` ar dtús agus ansin na crúcaí git:

```console
$ python -m pip install pre-commit
$ pre-commit install
```

*Windows*

```doscon
...\> py -m pip install pre-commit
...\> pre-commit install
```

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

## Stíl Python

- 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](https://editorconfig.org/) 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.

  Use [flake8](https://pypi.org/project/flake8/) to check for problems in this area. Note that our
  `.flake8` file excludes some errors that we don't consider as gross
  violations. Remember that [**PEP 8**](https://peps.python.org/pep-0008/) is only a guide, so respect the style of
  the 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ú.

  Fá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:

  ```
  # Allowed
  f"hello {user}"
  f"hello {user.name}"
  f"hello {self.user.name}"

  # Disallowed
  f"hello {get_user()}"
  f"you are {user.age * 365.25} days old"

  # Allowed with local variable assignment
  user = get_user()
  f"hello {user}"
  user_days_old = user.age * 365.25
  f"you are {user_days_old} days old"
  ```

  ní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ú.
- Seachain ú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.

  Ú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.
- I 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.

  Tagairtí 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:

  ```
  def test_foo():
      """
      A test docstring looks like this (#123456).
      """
      ...
  ```
- Where applicable, use unpacking generalizations compliant with [**PEP 448**](https://peps.python.org/pep-0448/),
  such as merging mappings (`{**x, **y}`) or sequences (`[*a, *b]`). This
  improves performance, readability, and maintainability while reducing errors.

## Allmhairí

- Úsáid [isort](https://pypi.org/project/isort/) chun sórtáil iompórtála a uathoibriú ag baint úsáide as na treoirlínte thíos.

  Tús tapa:

  ```console
  $ python -m pip install "isort >= 7.0.0"
  $ isort .
  ```

  *Windows*

  ```doscon
  ...\> py -m pip install "isort >= 7.0.0"
  ...\> isort .
  ```

  Ritheann 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
  ```
- Cuir 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.

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

  Mar shampla (tá tuairimí chun críocha míniúcháin amháin):

  *`django/contrib/admin/example.py`*

  ```python
  # future
  from __future__ import unicode_literals

  # standard library
  import json
  from itertools import chain

  # third-party
  import bcrypt

  # Django
  from django.http import Http404
  from django.http.response import (
      Http404,
      HttpResponse,
      HttpResponseNotAllowed,
      StreamingHttpResponse,
      cookie,
  )

  # local Django
  from .models import LogEntry

  # try/except
  try:
      import yaml
  except ImportError:
      yaml = None

  CONSTANT = "foo"

  class Example: ...
  ```
- Úsáid allmhairí áisiúlachta aon uair atá Mar shampla, déan seo:

  ```
  from django.views import View
  ```

  in ionad:

  ```
  from django.views.generic.base import View
  ```

## Stíl teimpléad

Lean na rialacha thíos i gcód teimpléad Django.

- Ba chóir gurb é `{% leathnaíonn%}` an chéad líne neamh-trácht.

  Déan é seo:

  ```html+django
  {% extends "base.html" %}

  {% block content %}
    <h1 class="font-semibold text-xl">
      {{ pages.title }}
    </h1>
  {% endblock content %}
  ```

  Nó seo:

  ```html+django
  {# This is a comment #}
  {% extends "base.html" %}

  {% block content %}
    <h1 class="font-semibold text-xl">
      {{ pages.title }}
    </h1>
  {% endblock content %}
  ```

  Ná déan é seo:

  ```html+django
  {% load i18n %}
  {% extends "base.html" %}

  {% block content %}
    <h1 class="font-semibold text-xl">
      {{ pages.title }}
    </h1>
  {% endblock content %}
  ```
- Cuir spás amháin go díreach idir `{{`, ábhar athraitheach, agus `}}`.

  Déan é seo:

  ```html+django
  {{ user }}
  ```

  Ná déan é seo:

  ```html+django
  {{user}}
  ```
- I {% load...%} , liostaigh leabharlanna in ord aibítre.

  Déan é seo:

  ```html+django
  {% load i18n l10 tz %}
  ```

  Ná déan é seo:

  ```html+django
  {% load l10 i18n tz %}
  ```
- Cuir spás amháin go díreach idir `{%`, ábhar clibeanna, agus `%}`.

  Déan é seo:

  ```html+django
  {% load humanize %}
  ```

  Ná déan é seo:

  ```html+django
  {%load humanize%}
  ```
- Cuir ainm an chlib `{% block%}` sa chlib `{% endblock%}` mura bhfuil sé ar an líne chéanna.

  Déan é seo:

  ```html+django
  {% block header %}

    Code goes here

  {% endblock header %}
  ```

  Ná déan é seo:

  ```html+django
  {% block header %}

    Code goes here

  {% endblock %}
  ```
- Taobh 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:

  ```html+django
  {% if user.name|lower == "admin" %}
  ```

  Ná déan é seo:

  ```html+django
  {% if user . name | lower  ==  "admin" %}

  {{ user.name | upper }}
  ```
- Laistigh de theimpléad ag baint úsáide as `{% leathnaíonn%}`, seachain clibeanna {% block%} a chur isteach.

  Déan é seo:

  ```html+django
  {% extends "base.html" %}

  {% block content %}
  ```

  Ná déan é seo:

  ```html+django
  {% extends "base.html" %}

    {% block content %}
    ...
  ```

## Féach ar stíl

- I dtuairimí Django, ba chóir “iarratas” a thabhairt ar an gcéad pharaiméadar i bhfeidhm amharc.

  Déan seo:

  ```
  def my_view(request, foo): ...
  ```

  Ná déan seo:

  ```
  def my_view(req, foo): ...
  ```

## Stíl mhúnla

- Ba chóir go mbeadh ainmneacha réimse le litreacha beaga uile, ag úsáid béim in ionad CamelCase.

  Déan seo:

  ```
  class Person(models.Model):
      first_name = models.CharField(max_length=20)
      last_name = models.CharField(max_length=40)
  ```

  Ná déan seo:

  ```
  class Person(models.Model):
      FirstName = models.CharField(max_length=20)
      Last_Name = models.CharField(max_length=40)
  ```
- Ba 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.

  Déan seo:

  ```
  class Person(models.Model):
      first_name = models.CharField(max_length=20)
      last_name = models.CharField(max_length=40)

      class Meta:
          verbose_name_plural = "people"
  ```

  Ná déan seo:

  ```
  class Person(models.Model):
      class Meta:
          verbose_name_plural = "people"

      first_name = models.CharField(max_length=20)
      last_name = models.CharField(max_length=40)
  ```
- Ba 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):

  - Gach réimse bunachar sonraí
  - Tréithe bainisteoir saincheaptha
  - `Aicme Meta`
  - `def __str__()` and other Python magic methods
  - def sábháil () \`\`
  - def get\_absolute\_url () \`\`
  - Aon mhodhanna saincheaptha
- Má 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:

  ```
  class MyModel(models.Model):
      DIRECTION_UP = "U"
      DIRECTION_DOWN = "D"
      DIRECTION_CHOICES = {
          DIRECTION_UP: "Up",
          DIRECTION_DOWN: "Down",
      }
  ```

  De rogha air sin, smaoinigh ar úsáid:ref: field-choices-enum-typepes:

  ```
  class MyModel(models.Model):
      class Direction(models.TextChoices):
          UP = "U", "Up"
          DOWN = "D", "Down"
  ```

## Úsáid `django.conf.settings`

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:

Ceadaí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:

```
from django.conf import settings

settings.configure({}, SOME_SETTING="foo")
```

Mar 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:

```
from django.conf import settings
from django.urls import get_callable

default_foo_view = get_callable(settings.FOO_VIEW)
```

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

In 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\`.

## Ilghnéitheach

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

## Stíl JavaScript

Le haghaidh sonraí faoin stíl cód JavaScript a úsáideann Django, féach:doc: javascript.