Software Development Guidelines

If your software is not a work of art you have failed as a software developer.

Noob developers and people with move fast and break things mentality might tell you these are only nice-to-have or academical but do not be mistaken. These are essential for mission critical software, its supporting software and software you generally expect to work and maintain. Though your mileage may vary in details depending on language, purpose, etc.

In no particular order.

code design

  • code should be more or less SOLID

    • especially single responsibility and liskov.

    • uses reasonable abstractions, polymorphism and interfaces

    • input and output types are documented (widespread problem in dynamic languages)

    • tells, does not ask 2 3 aka avoids getters/setters

  • illegal states must be unrepresentable

  • code should be DRY

  • code should be KISS

    • avoids accidental complexity

      • unnecessary state

      • unnecessary temporary variables

      • imprecise naming

    • less moving parts reduces failure potential

  • is reasonably split into multiple projects, including version control repositories

  • inputs are parsed, validated and normalized on system boundaries

testing

  • software is fully covered by unit tests

  • does not depend on network (besides local interface)

  • uses little to no fakes

  • faking / test data input happens through CDI

  • ideally only at level of public interfaces

    • avoiding test invalidation by implementation detail changes

code style

  • lines are no longer than 74 characters to account for

    • terminal text editor in 80 columns with line numbers

    • email based review replies

    • must not affect naming, clarity and greppability

  • in case of long argument lists / function signatures consider

    • writing each argument on separate line

    • lines starting with a comma instead of ending on it

    • which

      • improves readability as shapes of such code structures are more unified and eyeballing the individual arguments is easier as argument separator (newline) clearly stands out (as opposed to "," in number of other tokens on single line)

      • makes clearer unified diffs in future changes

building & packaging

  • uses standard tools

    • preferrably makefiles

  • builds in single step

  • does not bundle dependencies

version control

  • git or better

  • linear history (as much as possible)

    • rebase before merge

    • no git-pull merge commits

  • contains good commit messages

documentation

  • much information can be documented through proper (sub)typing

    • eg. it is better to accept Nat without further documentation instead of an Int and explaining it is >0 in plain text.

  • lives in the same git repository as the code it documents.

  • uses standard and apropriate format

    • reStructuredText or better

  • written following the same principles as code (mostly)