Debian Codegraph @

docs/misc/design-philosophies.txt

raw
1 ===================
2 Design philosophies
3 ===================
4
5 This document explains some of the fundamental philosophies Django's developers
6 have used in creating the framework. Its goal is to explain the past and guide
7 the future.
8
9 Overall
10 =======
11
12 .. _loose-coupling:
13
14 Loose coupling
15 --------------
16
17 .. index:: coupling; loose
18
19 A fundamental goal of Django's stack is `loose coupling and tight cohesion`_.
20 The various layers of the framework shouldn't "know" about each other unless
21 absolutely necessary.
22
23 For example, the template system knows nothing about web requests, the database
24 layer knows nothing about data display and the view system doesn't care which
25 template system a programmer uses.
26
27 Although Django comes with a full stack for convenience, the pieces of the
28 stack are independent of another wherever possible.
29
30 .. _`loose coupling and tight cohesion`: https://wiki.c2.com/?CouplingAndCohesion
31
32 .. _less-code:
33
34 Less code
35 ---------
36
37 Django apps should use as little code as possible; they should lack boilerplate.
38 Django should take full advantage of Python's dynamic capabilities, such as
39 introspection.
40
41 .. _quick-development:
42
43 Quick development
44 -----------------
45
46 The point of a web framework in the 21st century is to make the tedious aspects
47 of web development fast. Django should allow for incredibly quick web
48 development.
49
50 .. _dry:
51
52 Don't repeat yourself (DRY)
53 ---------------------------
54
55 .. index::
56 single: DRY
57 single: Don't repeat yourself
58
59 Every distinct concept and/or piece of data should live in one, and only one,
60 place. Redundancy is bad. Normalization is good.
61
62 The framework, within reason, should deduce as much as possible from as little
63 as possible.
64
65 .. seealso::
66
67 The `discussion of DRY on the Portland Pattern Repository`__
68
69 __ https://wiki.c2.com/?DontRepeatYourself
70
71 .. _explicit-is-better-than-implicit:
72
73 Explicit is better than implicit
74 --------------------------------
75
76 This is a core Python principle listed in :pep:`20`, and it means Django
77 shouldn't do too much "magic." Magic shouldn't happen unless there's a really
78 good reason for it. Magic is worth using only if it creates a huge convenience
79 unattainable in other ways, and it isn't implemented in a way that confuses
80 developers who are trying to learn how to use the feature.
81
82 .. _consistency:
83
84 Consistency
85 -----------
86
87 The framework should be consistent at all levels. Consistency applies to
88 everything from low-level (the Python coding style used) to high-level (the
89 "experience" of using Django).
90
91 Models
92 ======
93
94 Explicit is better than implicit
95 --------------------------------
96
97 Fields shouldn't assume certain behaviors based solely on the name of the
98 field. This requires too much knowledge of the system and is prone to errors.
99 Instead, behaviors should be based on keyword arguments and, in some cases, on
100 the type of the field.
101
102 Include all relevant domain logic
103 ---------------------------------
104
105 Models should encapsulate every aspect of an "object," following Martin
106 Fowler's `Active Record`_ design pattern.
107
108 This is why both the data represented by a model and information about
109 it (its human-readable name, options like default ordering, etc.) are
110 defined in the model class; all the information needed to understand a
111 given model should be stored *in* the model.
112
113 .. _`Active Record`: https://www.martinfowler.com/eaaCatalog/activeRecord.html
114
115 Database API
116 ============
117
118 The core goals of the database API are:
119
120 SQL efficiency
121 --------------
122
123 It should execute SQL statements as few times as possible, and it should
124 optimize statements internally.
125
126 This is why developers need to call ``save()`` explicitly, rather than the
127 framework saving things behind the scenes silently.
128
129 This is also why the ``select_related()`` ``QuerySet`` method exists. It's an
130 optional performance booster for the common case of selecting "every related
131 object."
132
133 Terse, powerful syntax
134 ----------------------
135
136 The database API should allow rich, expressive statements in as little syntax
137 as possible. It should not rely on importing other modules or helper objects.
138
139 Joins should be performed automatically, behind the scenes, when necessary.
140
141 Every object should be able to access every related object, systemwide. This
142 access should work both ways.
143
144 Option to drop into raw SQL easily, when needed
145 -----------------------------------------------
146
147 The database API should realize it's a shortcut but not necessarily an
148 end-all-be-all. The framework should make it easy to write custom SQL -- entire
149 statements, or just custom ``WHERE`` clauses as custom parameters to API calls.
150
151 URL design
152 ==========
153
154 Loose coupling
155 --------------
156
157 URLs in a Django app should not be coupled to the underlying Python code. Tying
158 URLs to Python function names is a Bad And Ugly Thing.
159
160 Along these lines, the Django URL system should allow URLs for the same app to
161 be different in different contexts. For example, one site may put stories at
162 ``/stories/``, while another may use ``/news/``.
163
164 Infinite flexibility
165 --------------------
166
167 URLs should be as flexible as possible. Any conceivable URL design should be
168 allowed.
169
170 Encourage best practices
171 ------------------------
172
173 The framework should make it just as easy (or even easier) for a developer to
174 design pretty URLs than ugly ones.
175
176 File extensions in web-page URLs should be avoided.
177
178 Vignette-style commas in URLs deserve severe punishment.
179
180 .. _definitive-urls:
181
182 Definitive URLs
183 ---------------
184
185 .. index:: urls; definitive
186
187 Technically, ``foo.com/bar`` and ``foo.com/bar/`` are two different URLs, and
188 search-engine robots (and some web traffic-analyzing tools) would treat them as
189 separate pages. Django should make an effort to "normalize" URLs so that
190 search-engine robots don't get confused.
191
192 This is the reasoning behind the :setting:`APPEND_SLASH` setting.
193
194 Template system
195 ===============
196
197 .. _separation-of-logic-and-presentation:
198
199 Separate logic from presentation
200 --------------------------------
201
202 We see a template system as a tool that controls presentation and
203 presentation-related logic -- and that's it. The template system shouldn't
204 support functionality that goes beyond this basic goal.
205
206 Discourage redundancy
207 ---------------------
208
209 The majority of dynamic websites use some sort of common sitewide design --
210 a common header, footer, navigation bar, etc. The Django template system should
211 make it easy to store those elements in a single place, eliminating duplicate
212 code.
213
214 This is the philosophy behind :ref:`template inheritance
215 <template-inheritance>`.
216
217 Be decoupled from HTML
218 ----------------------
219
220 The template system shouldn't be designed so that it only outputs HTML. It
221 should be equally good at generating other text-based formats, or just plain
222 text.
223
224 XML should not be used for template languages
225 ---------------------------------------------
226
227 .. index:: xml; suckiness of
228
229 Using an XML engine to parse templates introduces a whole new world of human
230 error in editing templates -- and incurs an unacceptable level of overhead in
231 template processing.
232
233 Assume designer competence
234 --------------------------
235
236 The template system shouldn't be designed so that templates necessarily are
237 displayed nicely in WYSIWYG editors such as Dreamweaver. That is too severe of
238 a limitation and wouldn't allow the syntax to be as nice as it is. Django
239 expects template authors are comfortable editing HTML directly.
240
241 Treat whitespace obviously
242 --------------------------
243
244 The template system shouldn't do magic things with whitespace. If a template
245 includes whitespace, the system should treat the whitespace as it treats text
246 -- just display it. Any whitespace that's not in a template tag should be
247 displayed.
248
249 Don't invent a programming language
250 -----------------------------------
251
252 The goal is not to invent a programming language. The goal is to offer just
253 enough programming-esque functionality, such as branching and looping, that is
254 essential for making presentation-related decisions. The :ref:`Django Template
255 Language (DTL) <template-language-intro>` aims to avoid advanced logic.
256
257 Safety and security
258 -------------------
259
260 The template system, out of the box, should forbid the inclusion of malicious
261 code -- such as commands that delete database records.
262
263 This is another reason the template system doesn't allow arbitrary Python code.
264
265 Extensibility
266 -------------
267
268 The template system should recognize that advanced template authors may want
269 to extend its technology.
270
271 This is the philosophy behind custom template tags and filters.
272
273 Views
274 =====
275
276 Simplicity
277 ----------
278
279 Writing a view should be as simple as writing a Python function. Developers
280 shouldn't have to instantiate a class when a function will do.
281
282 Use request objects
283 -------------------
284
285 Views should have access to a request object -- an object that stores metadata
286 about the current request. The object should be passed directly to a view
287 function, rather than the view function having to access the request data from
288 a global variable. This makes it light, clean and easy to test views by passing
289 in "fake" request objects.
290
291 Loose coupling
292 --------------
293
294 A view shouldn't care about which template system the developer uses -- or even
295 whether a template system is used at all.
296
297 Differentiate between GET and POST
298 ----------------------------------
299
300 GET and POST are distinct; developers should explicitly use one or the other.
301 The framework should make it easy to distinguish between GET and POST data.
302
303 .. _cache-design-philosophy:
304
305 Cache Framework
306 ===============
307
308 The core goals of Django's :doc:`cache framework </topics/cache>` are:
309
310 Less code
311 ---------
312
313 A cache should be as fast as possible. Hence, all framework code surrounding
314 the cache backend should be kept to the absolute minimum, especially for
315 ``get()`` operations.
316
317 Consistency
318 -----------
319
320 The cache API should provide a consistent interface across the different
321 cache backends.
322
323 Extensibility
324 -------------
325
326 The cache API should be extensible at the application level based on the
327 developer's needs (for example, see :ref:`cache_key_transformation`).