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