python/lib/django_1_4/docs/misc/design-philosophies.txt

   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`: http://c2.com/cgi/wiki?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     __ http://c2.com/cgi/wiki?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`: http://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 If we wanted to put everything in templates, we'd be using PHP. Been there,
 207 done that, wised up.
 208
 209 Discourage redundancy
 210 ---------------------
 211
 212 The majority of dynamic Web sites use some sort of common sitewide design --
 213 a common header, footer, navigation bar, etc. The Django template system should
 214 make it easy to store those elements in a single place, eliminating duplicate
 215 code.
 216
 217 This is the philosophy behind :ref:`template inheritance
 218 <template-inheritance>`.
 219
 220 Be decoupled from HTML
 221 ----------------------
 222
 223 The template system shouldn't be designed so that it only outputs HTML. It
 224 should be equally good at generating other text-based formats, or just plain
 225 text.
 226
 227 XML should not be used for template languages
 228 ---------------------------------------------
 229
 230 .. index:: xml; suckiness of
 231
 232 Using an XML engine to parse templates introduces a whole new world of human
 233 error in editing templates -- and incurs an unacceptable level of overhead in
 234 template processing.
 235
 236 Assume designer competence
 237 --------------------------
 238
 239 The template system shouldn't be designed so that templates necessarily are
 240 displayed nicely in WYSIWYG editors such as Dreamweaver. That is too severe of
 241 a limitation and wouldn't allow the syntax to be as nice as it is. Django
 242 expects template authors are comfortable editing HTML directly.
 243
 244 Treat whitespace obviously
 245 --------------------------
 246
 247 The template system shouldn't do magic things with whitespace. If a template
 248 includes whitespace, the system should treat the whitespace as it treats text
 249 -- just display it. Any whitespace that's not in a template tag should be
 250 displayed.
 251
 252 Don't invent a programming language
 253 -----------------------------------
 254
 255 The template system intentionally doesn't allow the following:
 256
 257 * Assignment to variables
 258 * Advanced logic
 259
 260 The goal is not to invent a programming language. The goal is to offer just
 261 enough programming-esque functionality, such as branching and looping, that is
 262 essential for making presentation-related decisions.
 263
 264 The Django template system recognizes that templates are most often written by
 265 *designers*, not *programmers*, and therefore should not assume Python
 266 knowledge.
 267
 268 Safety and security
 269 -------------------
 270
 271 The template system, out of the box, should forbid the inclusion of malicious
 272 code -- such as commands that delete database records.
 273
 274 This is another reason the template system doesn't allow arbitrary Python code.
 275
 276 Extensibility
 277 -------------
 278
 279 The template system should recognize that advanced template authors may want
 280 to extend its technology.
 281
 282 This is the philosophy behind custom template tags and filters.
 283
 284 Views
 285 =====
 286
 287 Simplicity
 288 ----------
 289
 290 Writing a view should be as simple as writing a Python function. Developers
 291 shouldn't have to instantiate a class when a function will do.
 292
 293 Use request objects
 294 -------------------
 295
 296 Views should have access to a request object -- an object that stores metadata
 297 about the current request. The object should be passed directly to a view
 298 function, rather than the view function having to access the request data from
 299 a global variable. This makes it light, clean and easy to test views by passing
 300 in "fake" request objects.
 301
 302 Loose coupling
 303 --------------
 304
 305 A view shouldn't care about which template system the developer uses -- or even
 306 whether a template system is used at all.
 307
 308 Differentiate between GET and POST
 309 ----------------------------------
 310
 311 GET and POST are distinct; developers should explicitly use one or the other.
 312 The framework should make it easy to distinguish between GET and POST data.