PageRenderTime 38ms CodeModel.GetById 11ms RepoModel.GetById 1ms app.codeStats 0ms

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