My completed code will tend to match the following measures. These are heuristics rules not dogmatism.:

  • General readability measures
    • Code is organised in classes (non-OO language still use modules).
    • The API of a class is organised into messages that make sense inside domain of the object.
    • The names of the API should be concise and non-ambiguous.
    • Params, exceptions and returns should be tagged to the compiler, and in the unit docs. That requires a sensible name and a type.
    • Avoid non-dictionary abbreviations or acronyms in visible data (i.e. constants, API or classes). Companies and department names are an exception to this. HTML is fine, HTMLv4_01 is fine, BT21CNclient is fine, realImpl is not, reg0A34 is not.
    • Although in PHP, constants are not really special; use of constants generally improves readability. In particular flag values must be constants, as this allows refactoring better, when the requirements change.
    • Defines are not constants. All other things being equal, constants are better, as they follow namespace rules.
    • Most people define constants in caps 1 2.
    • Orthogonality 3 is valued.
    • In old hardware more than 5 param was inefficient use of registers; this doesn't matter anymore but I apply this limit as a number of the things that a human is likely to be able to retain in short term memory. This is awkward for functional programming.
    • Like graph titles, every class should be definable by a single sentence “a class to...".
    • An optimised architecture leads to much better outcomes than optimised code.
  • Code complexity measures
    • Complex code REQUIRES unit tests.
    • The basic/minimal structure is a function or method.
    • I think functions may only have one entry point, but may have many exits (for high level languages, like Python). Other people disagree on this statement e.g. 4 5 6, but tend to use C.
    • I test on the negative, and die/return early. This makes the code easier to read, and less indented (but is terrible in C).
    • Complex code MUST be documented, in the API doc header; and this MUST be updated. Complex code is not 'cool' or 'professional'.
    • Functions should be <=50lines, excluding documentation.
    • Classes should be <=400lines, excluding documentation.
    • Classes should have <7methods excluding the constructor and any DI setters. More than this means you have too much responsibility in a single class.
    • I favour loops over branching, as it can be extended/enhanced faster and more safely. If a behaviour is true for 1..N, it is trivial to make to true for N+1. This is doesn't execute as quickly, but in most cases, on a per instruction, level coder time is more important than execution time. I am aware that “Those who do not study Lisp are doomed to reimplement it, poorly” 7 in every major coding project.
    • I use Facades 8 quite often (see 50line function constraint).
    • If you can't work out how to document a function; you can't test it, so it needs to be refactored.

Code metrics

RSS. Share: Share this resource on your twitter account. Share this resource on your linked-in account. G+

Code metrics

RSS. Share: Share this resource on your linked-in account. Share this resource on your twitter account. G+ ­ Follow edited