Changes between Initial Version and Version 1 of website/workStandards

Timestamp:

03/28/13 15:42:55 (4 years ago)

Author:

mark

Comment:

--

website/workStandards

@@ +1 @@
+= Work Standards =
+
+Drupal is powerful and flexible.  There are often many alternative solutions to any problem.  Drupal is also a thriving community, made up of lots of people with different (sometimes conflicting) ideas.  And Drupal changes quickly.  If the community finds a better way of doing something, they often drop older methods.  That means if you're not careful, your Drupal website could become difficult to upgrade if the tools and approaches you use become deprecated.
+
+When you build with Drupal, you're accepting both the good and the bad in this.  The best way to avoid the bad, is to keep your working practices closely in tune with the majority of the Drupal community.  "Go it alone" at your own risk. Or rather, don't! In the Transition Network, we like to minimise risk.
+
+Being a member of the Transition Technologists team means you agree to follow these best practices.  Ignoring them will undermine collaboration and cost us more time and money in the long-term.
+
+== Choose well-supported modules with a strong history and developer base ==
+
+When picking "contributed" Modules (Modules that aren't included in Drupal Core, but are available through the community at drupal.org/project/modules), try to use the following criteria when picking new Modules to add:
+
+* Has the statuses "actively maintained" and "under active development".
+* Reportedly in use on at least a few thousand website.
+* Have evidence of long-term development. (Look for versions for the last one or two Drupal versions before the current one).
+* Shows commitment to prompt future upgrading - many modules say something like "we commit to having a Drupal 8 version available on the day Drupal 8 stable is released".
+
+Beyond that, it also help to double check modules that perform a similar function to each other, read through their issue queues, and look for signs that they might be merging, or becoming deprecated.  If in doubt, ask in the Drupal forums, or ask a more experienced Drupal developer on in the Transition Technologists team.
+
+== Follow Drupal coding standards ==
+
+Drupal has some fairly clear [[https://drupal.org/coding-standards|coding standards]]. It's not about one way being more right than another, but following Drupal's standards helps us keep our code consistent for when newcomers have to pick up where we left off.  So, follow them!
+
+== Pick good names for things ==
+
+Names for things (CSS classes, Views, Content Types, Panels) are often very hard to change.  So choose once and choose well.  Make names:
+
+* Descriptive and intuitive.
+* Concise (a compromise with with "Descriptive and intuitive").
+* Extensible.
+
+Most of us building with Drupal will be responsible for naming things.  If we're developing HTML+CSS, we may need to define class names.  If we're building Views and Panels, we need to give those things "machine names".  Unfortunately, it's difficult to set rules for naming.  It requires creativity, judgement and common-sense.  So here's some good vs bad names which hopefully give you an idea.
+
+||= Context =||= Bad =||= Good =||
+|| CSS class for a coloured box   ||  .yellow-bg (colour might change in future)  ||  .highlighted  ||
+|| View name for a latest news page   ||  latest (too vague)  ||  news_latest  ||
+|| View name for an events listing   ||  calendar_3 (too vague, may not always be a calendar)  ||  events  ||
+
+== Try to group Views together ==
+
+The Views module makes it possible to create multiple displays under one View.  For example, a page, a Block, and a Panels content pane.  We should avoid creating all of these as separate Views, for two reasons.
+
+Firstly, we'd be missing out on an opportunity to reduce work.  When Views displays are grouped under one View, adding a Field to one display can add that Field to all grouped displays.  We can also override a specific display where needed, but there is the ability here to minimise work and make global changes.
+
+Secondly, the Views admin page is hard enough for newcomers to wade through as it is.  The more Views displays are grouped, the easier it is to look at the Views admin page and work out what's going on, where.
+
+Great practice for naming various views displays is thus (the machine name for the following view might be "news"):
+
+||= View display =||= machine name =||
+|| Main news page || news_all ||
+|| Latest news Block || news_latest ||
+|| Related news Block || news_related_tag ||