Basic Coding Style
- Use two spaces per level of indent. (Do not use tabs or mix the indents.)
- Always use
snake_case, for functions, “methods” and variables. Use
CappedCamelCasefor “class” names, e.g.
var liveWhale = new LiveWhale();.
- Despite Mislav’s blog post and the ensuing debate it caused, use semicolons for clarity. If you don’t want to use semicolons, then write CoffeeScript. :)
//for comment blocks (instead of
/* */). See documentation below.
- Don’t ever use
$.post. Instead use
$.ajaxand provide both a success handler and an error handler.
- Use events rather than direct calls of alternative module/class/object methods. For jQuery, use
<!-- when listing issues --> <ul class="issues list" data-query-uri="/issues?milestone=none"> <!-- or, an individual issue --> <li class="issue" data-issues-number="76" data-issues-state="open" data-issues-milestone="none">
# coffeescript unless String::toDate String::toDate = () -> return new Date(this.toString()) if this.isISO8601() new Date()
White Whale custom client work and Developer-made modules should use their own top-level namespaces.
$.noConflict() to keep everything separate and is loaded into
window.livewhale.jQuery should you wish to use it. (If choosing to do that, be aware that we upgrade LiveWhale’s jQuery regularly and you would be subject to our upgrade schedule.)
When extensive REST-style functionality is needed, LiveWhale is agnostic of course and White Whale has not yet made a determination as to a preferred library for the CMS’ use. The LiveWhaleScreens widget uses Backbone, supported by Underscore and jQuery, and the developer Roadmap does as well. However, the LiveWhale team is investigating the use of Angular as a tool for the CMS’ use.
Rather than bless specific documentation software, we follow these guidelines as best possible regardless of the tool:
- Comments should be renderable into HTML via Markdown.
- Prepend your functions/methods with commented documentation. Use
#for CoffeeScript unless your tool requires otherwise.
- You may endline comments when the script is not explicit enough on its own, but it is not required.
- For simple or obvious methods/functions, simply describe the what it does.
- For complex methods/functions, do the full but: list expected parameters with type and whether they are required or not; show sample usage (signature) and type any returned value(s).
Note: LiveWhale version 1.5+ ships with jQuery version 1.10.2