Clean Code Development

don’t bore your readers by stating the same again and again — build viable abstractions instead. Avoid duplicated functionality, remove unnecessary data redundancy, automate repetitive tasks.

“Everything should be made as simple as possible, but not simpler” (Einstein). Write code foremost to be understandable. Resist using an interesting solution, when there also is a straight forward (albeit boring) standard solution.

distrust your own cleverness. “More computing sins are committed in the name of efficiency than for any other single reason – including blind stupidity” (W.A.Wulf). Defer improvements “for later”. Require an objective proof for performance problems, based on real-world data.

build up functionality from self-contained abstractions, instead of cleverly extending, bending or specialising. Avoid proliferation of special cases.

whenever you enter some area, leave it in somewhat better shape than you found it

never do “programming by coincidence”. Try to understand why something works or breaks. Never act based on assumptions. Don’t treat symptoms. Better don’t act unless you understand.

use a revision control system. Create thematically consistent change sets, write clear commit messages, learn to handle branching and merging.

apply the fundamental refactorings “_extract method_” and “_rename_” liberally.

review your own achievements based on the principles (especially but not limited to those you’re focussing on currently). Partition your work into tasks which can be finished on one day. Take the time to reflect.

each piece of code should talk on a distinctive level of granularity. Don’t mix implementation details with invocation of high-level abstractions. Refactor code to balance the level of abstraction.

every class or entity should deal with one topic solely, and do that well. What needs to be said for a given concern, should be found at a single location.

decompose functionality into orthogonal concerns. Increase focussing and cohesion within a single concern, and decrease coupling amongst separate concerns.

establish writing conventions based on readability. Code is more often read than written. Reason about the purpose of conventions, then stick to them. Especially focus on naming conventions and correct source code comments. Comments should not detail what you do, but the purpose why you do it.

capture problems and work items as well delineated issues. Track them in a structured way, establish ubiquitous procedures for assigning and resolving issues.

verify correct integration of the parts by running tests automatically. Build a safety net allowing to perform refactorings while retaining correct operation.

acquire an attitude of concern for the ongoing evolution of the coding craft. Read books, journals and blogs. Learn a new programming language every year.

four eyes are better then two. Present and explain your code to other programmers. Establish practices like code reviews and pair programming.

keep interfaces focussed and confined to a set of operations likely to be used in conjunction. Avoid to tie clients to the details of a service implementation

revert dependencies with respect to the naive logical meaning. Instead of implementing high-level functions through low-level functions, turn the latter into services and thus make both depend on interfaces.

the special case must be able to stand-in for the general concept in all respects. A subclass instance is required to take on all responsibilities outlined by the Interface. The special case must not extend and bend the meaning beyond what was outlined in the abstraction. An ellipse can’t be kind-of a circle.

every piece of code should behave exactly in the way obvious from the names, the concepts and the general context. The reader should be able to get the essence of what’s going on already from the first coarse-grained view.

every part — be it function, object, interface or subsystem — should expose only the bare minimum required to use it effectively.

cover individual components with tests in isolation. Break the reasoning in terms of contracts down to the implementation level

build mock-ups, dummies, stubs and fakes to create a controlled environment for reasoning and test.

base your reasoning and testing on coverage analysis (instructions, branches, decisions).

apply the more advanced types of refactoring techniques to rearrange and restructure code fluently. Ensure correctness through your stock of unit tests.

participate actively, beyond the local team. Report bugs, provide testcases, work with library developers, visit local user groups, participate in conferences.

any class or functional unit should be open towards extensions, but closed against modifications. Extending it should not require changing the internals, nor tie the extension to these internals. Increase cohesion, decrease coupling.

invoke services instead of doing things yourselves. Don’t inspect state and operate from the outside. Respect Subsidiarity.

don’t write “train wreck code”. Talk to direct collaborators only. Within each scope, confine yourself to using the parameters, local methods, locally created objects, associated partners and global services.

integrate changes timely and frequently. Perform this integration process automatically, in a controlled and reproducible environment, perform the unit and integration test suites as part of this process.

use Dependency Injection to implement IoC. Use service locators, employ the DI patterns or use an existing DI container implementation or framework.

use static analysis and similar quantitative measurements to monitor various aspects of a source base

observe instead of assuming. Monitor the code quality, measure performance, observe defect rates. Estimate efforts and verify your guesses after the fact. Identify impediments.

share your experience and knowledge. Explaining something is the best way to understand it yourself.

clearly delineate planning and doing. Design must not duplicate implementation work, and implementation concerns must not interfere with architectural considerations. Otherwise implementation will supersede the design and the real system will end in chaos.

code in accordance with design. Traces of architecture should be visible down into individual implementation structures, names, organisation of the code base and the runtime structure. Never play tricks to undermine and thwart the design and create a second reality.

decide later and don’t do it, if in doubt. Question your own brilliant ideas — write them down, but defer implementation for later, because, well, you ain’t gonna need that crap. Don’t say “I can do that on a single afternoon” — be prudent: doing it seriously will be a major undertaking. Refrain from spending effort without a reason.

extend the automated continuous integration into deployment and setup. Plan and test the steps towards an release, and finally automate them. Create a platform to roll out development snapshots, integration builds, release candidates and service updates.

development is a learning process. Instead of achieving perfection through a single big bang, proceed in incremental steps and include feedback from the user or customer. Use each iteration for a retrospective and adjust your procedures.

employ the thinking in terms of components and contracts from the largest to the smallest. Each component establishes some kind of isolation, which helps to cut down complexity.

start from the usage situation. Each unit, class, component or subsystem has clients. Instead of detached planning, or worse, guessing what might be cool, work out the requirements and contract from an exemplary use in code. Transform this into a test before you even think about how to make it work.