Code Conventions Routines
From MapbenderWiki
Contents |
Why routines?
- to avoid duplicate code: copy and paste is a design error
- to reduce complexity
- to produce code with strong, functional cohesion: doing one thing only and doing it well
- make a section of code readable
Layout
- seperate routine parameters by one space
- seperate routines by at least one blank line
- routine names: first letter lowercase, first letter of each following word uppercase. Underscore is forbidden!
- unresolved: add a semicolon add the end of a function (after the closing curly brace). This would enable us to use Edwards packing algorithm (thanks to User:Marc Jansen for the hint)
Good routine names
- use a strong verb followed by an object, like printDocument() or checkOrderInfo()
- good names describe everything the routine does
- make names as long as necessary
- avoid meaningless names (like handleCalculation() or performService() etc.)
- maybe use a description of the return value
- in classes, don't include the object name again (document.print() and not document.printDocument())
- establish conventions for common operations (avoid mixtures like id(), getId() etc.)
Routine length
> 200 lines: understandability suffers
Routine parameters
- sort order: input parameters first, then output parameters
- if several routines use similar parameters, use a consistent order
- don't use routine parameters as working variables
- > 7 parameters: readability suffers
- check values of all data from external sources / all routine parameters (garbage in garbage out is not an option: either "garbage in, nothing out" or "garbage in, error message out")
- decide how to handle bad inputs (robustness vs correctness)
- anticipate divide by zero errors, or division by integer
General advice
- minimize the number of returns in a routine, but return a value immediately if it improves readability
- don't use recursion if you can use sequential code (Fibonacci etc)
- create simply routines for simple purposes
- move complicated boolean tests into routines
- add a notice to deprecated functions
- make sure that you don't use operators as functions! For example write
if (typeof myVar === "undefined") {
instead of
if (typeof(myVar) === "undefined") {
