docs/misc/design-philosophies.txt

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