PS Best Practices

From VYRE

Jump to: navigation, search

Contents

Generic

  • The name of an entity is the most important describer of its function. Whether this is for a page, content store, variable, JavaScript function or HTML id this should always describe what it is being used for.
  • Always comment your code. Until we all program perfectly, in exactly the same way we will always need comments. Make sure complex areas of code contain comments on its function.
  • When coding, place yourself in others’ shoes. Remember that someone else is going to have to read your code.
  • Always perform cross browser testing. Any CSS or JavaScript change can cause browser issues.


Unify Specific

  • Site session timeout should be as short as possible to keep memory usage small. The default of 30 minutes is usually suitable for a CMS based site, where as 10 minutes is more suitable for a public facing site.
  • Page templates should include only the resources (CSS, Scripts etc) that are necessary for the pages that use them to function. Favour multiple, slightly differing page templates over one general template to ensure that there are no unneeded requests.
  • Description fields should be as explanatory as possible - they should give a good explanation of what the code is doing and where is it used.
  • Script bundles – where possible, use CSS and JavaScript bundles to reduce the overall number of requests.
  • Error pages - 404, Error and Unauthorized pages should execute no logic, be as lightweight as possible, and be statically cached.
  • Do not reference externally hosted resources. If the hosting server doesn’t respond you have to wait for the browser request timeout before the page will complete loading.
  • Redirect Pages – favour one redirect page that accepts parameters over multiple specific pages
  • Caching strategy should be considered alongside page / IA design. It will always be easier to cache a page whose caching potential has been factored into the design.
  • Cache types should be favoured in this order – Page, Content Area, Portlet.
  • Subtractive caching where the page is cached and non cacheable elements are removed should be favoured over multiple portlet caches.
  • Item Multiplicity should always be noted – an item linked to thousands of other items is going to cause issues.
  • Saved Search description fields should contain a verbal interpretation of the saved search syntax.
  • Unused files services should be disabled early. There are many default files services enabled by default, many of which are not needed. It is very difficult to determine after a site has been built, which services are not being used
  • Saved Search fields options - Favour using the + - field options for creating saved searches as this is faster than using the query syntax.


XSL

  • XSL includes lines should be commented to describe the functionality being included.
  • XPath expressions should be as simple as possible. When they have to be complicated, ensure they contains comments as to their function.
  • Templates should be labeled semantically – either with semantic names, modes or comments.
  • Favour small discrete templates than large multi functional ones.
  • Prefer applying templates with predicate over for-each loops with conditionals.
  • When applying to templates, get as close to target node as possible.
  • Use modes to improve specificity – it's better to have two small templates matching the same node and performing different tasks than one template performing two tasks using a conditional.
  • Minimize document traversal – any select expression causes some sort of document traversal.
  • Rooted XPath expressions shouldn’t be used unless absolutely necessary.
  • Avoid using // in expressions – this will cause you to visit every descendent.
  • Use XPath Axis over relative (.../) or rooted (/) expressions.
  • Use named templates only when the context node, position and size have no influence on the result of the template – ie when it’s a pure function that computes results based purely on the parameters passed.
  • Use the Muenchian method for grouping.
  • Use XSL pipelining to describe complex model data / domain logic
  • Use EXLT and Xalan Java Extensions to execute complex data manipulation – eg dates, math functions, string manipulation.


JavaScript

  • Write JavaScript in external scripts. Only instantiation and configuration code should go in the page.
  • JavaScript files should be included at the bottom of the page (or as low in the page as possible) so they are last to be requested as JavaScript request block other requests.
  • Object Oriented JavaScript should be preferred to procedural.
  • Code towards stateful classes that encapsulate the domain concerned.
  • Use appropriate object structures – arrays for list data, maps for lookup.
  • JQuery should only be used for DOM manipulation
  • Not all third party JavaScript libraries are of good quality. Read the source code and check comments and bug lists.
  • Use appropriate JavaScript libraries – including a 60kb library just for one function is wasteful.
  • DOM elements with attached events should be commented. It is very difficult to find the functionality of a button if its event handler is defined in an included file.


JSP / JSTL / Java

  • Use scriptlets to execute business logic and place model data in pageContext object.
  • Access scoped object data (pageContext, request and session) using EL Expressions (${ })
  • Use JSTL for presentation logic
  • Use appropriate scope -
    • Page Scope (pageContext) – Only bound to the current page of the current request. This does not require explicit cleanup.
    • Request Scope (request) – Bound to all pages of the current request – needs no cleanup.
    • Session scope (session) – bound to the user session. Session scope attributes should be prefixed with a unique identifier to prevent overwriting of common named attributes. Session scope attributes should be explicitly cleaned up when finished.
    • Application Scope – bound to the whole application, only use when absolutely necessary and always cleanup after use.
  • Place custom Java classes and libraries in the tomcat/custom folder.


CSS

  • Avoid Using Inline Styles
  • Be specific / learn specificity (avoid !important)
  • Make sure you have a css reset
  • Use px for sizes
  • Put Stylesheets at the top
  • Don’t Repeat Yourself
  • Use CSS shorthands


SEO

  • Headings should be placed in logical order, h1 h2 h3 etc, there should never be an h2 on a page without an h1.
  • Image alt tags should contain meaningful sentences (remember they are also used by screen readers), "The small hut on a hill" is much better than "hut, hill, surrey" never keyword stuff alt tags.
  • <a> tags should always have titles that are descriptive and different from the actual link text, for example, a read more link should use the article's title for the title text <a href="#" title="Introduction to something or other">Read more...</a>
  • Every site should have a sitemap in some form. As this should ideally point to every page, it allows spiders to easily and quickly traverse large sites.
  • Do not overdo javascript, although spiders are now getting better they still cannot cope amazingly well with js heavy sites. This is especially important to remember when using links. <a href="javascript:void();">link</a> will do both you and your clients no favours at all.
  • Page titles and descriptions should be unique on every page. Although this is not always possible it really does help search indexing, if a spider sees 50 pages with the same title and same description, then they will more than likely be assumed as the same page in different locations of the site.
  • HTML layout should have the content as the first thing on the page. This may seem odd but when you think about it it makes perfect sense. When developing a page that has top and side navigation, the following is generally how you would code it:
<body>
    <div id="topNav">
        <ul>....Massive load of li's</ul>
    </div>
    <div id="sideNav">
        <ul>....Massive load of li's</ul>
    </div>
    <div id="content">
        Various bits of wafflage
    </div>
</body>

When coded like this, the spider see loads and loads of page irrelevant content, ie two loads of navigation. A better way is the following:

<body>
    <div id="content">
        Various bits of wafflage
    </div>
    <div id="topNav">
        <ul>....Massive load of li's</ul>
    </div>
    <div id="sideNav">
        <ul>....Massive load of li's</ul>
    </div>
</body>

and use css to reorganise the page. This also makes it alot nicer for screen readers and mobile browsers as they also get straight to the content without having to trawl through loads of navigation.

Personal tools