Clean Code

“Keep it Clean, Your Mother Doesn’t Work Here”

William PenberthyApplication Development Consultant

RBA, Inc.

Description of the Next 70 Minutes

We will discuss the importance of clean code

• What it is• Identifying clean vs dirty• Making it clean• Keeping it clean• Cleaning up after others

Intro

WTF – Clean Code??

• Easy to understand the structure

• Easy to understand the logic

• Reasons for the decisions are documented

Why Clean Code??

• Ability to respond to change requests stays constant

• Comparatively easy to bring new resources into project

• Unit test code coverage becomes a useful statistic

• Issue detection and resolution is more efficient

Indications of “Bad” Structure

• Opacity/Obscurity – a lot of time is spent trying to understand what is happening in the code

• Needless complexity – remember KISS!

• Magic Numbers / “configuration” items that never change

• Common features built into high level project (logging, data access)

Indications of “Good” Structure

• Loosely coupled projects• Dependencies are obvious• Names and namespaces are useful and descriptive• Consistency • Abstractions rather than concretions• Logical separation of concern

Examples of Unclean Logic

• Fragility – one change breaks many things• Rigidity – difficult to change without

having to make many other changes• Code Duplication• Methods with Too Many Arguments • Nesting without implicit ends

More Dirtyness (technical term)

• Clutter and code that has been commented for a looooong time• Too much information in an interface• Unit tests are “turned off” or commented out• Unmanaged build warnings• Compound methods –

GetList().First(x=>x.IsActive).GetFullName();

Examples of Clean Logic

If your code is clean, it will probably have these…

Method management

• Each method does only one thing • Loops, exception handling, etc should all be encapsulated in

other “sub” methods• No out variables• No ref variables - Return complex object holding all values, split

into several methods. If your method must change the state of something, have it change the state of the object it is called on• No Selector / Flag Arguments – these should be different

methods

Naming Interfaces and Classes in a Related Manner• The name of an interface should be derived

from its usage by the client

• Name Classes After How They Implement Their Interfaces• MemoryStream implementing IStream• SqlCommand implementing ICommand• ObservableCollection implementing Ilist (it

ain’t perfect)

Prefer Dedicated Value Objects to Primitive Types• Instead of passing primitive types like

strings and integers, use a dedicated type• AbsolutePath instead of string• Uri instead of string

• Rather than create a list of parameters, create a class or struct to hold the information

Supporting Clean Code

• External Documentation• Business requirements• Technical design• Coding standards

• Internal Process• Continual refactor (10-20% of effort every sprint/cycle)• Code review• Technical debt log

Exception Handling Strategy

• Catch exceptions as specific as possible so you can react in a meaningful manner

• If you can’t react in a useful way to an exception, let something up the call stack handle it

• Fail fast – as early in the process as possible

• DON’T SWALLOW EXCEPTIONS!

Boy Scout Rule

• Keep the code cleaner then you found it

• If there is technical debt in a method you are refactoring, clean it up

• While you are there, clean up one more level

• Ensure new code is clean

Separate and Clarify Multi-Threading Code• Do not mix code that handles multi-threading in with

non-threading code. Separate them into different classes

• When using asynchronous methods (async) use Async as part of the name• DoWorkAsync• DoDifferentWorkAsync

Coding Standards – Have Them

• Don’t have pages describing what case to use in variables, or how many spaces to indent• Talk about patterns to use• Base classes and their differentiation• How to call the server• Expected consistent behavior• What gotchas there are in the implementation \ architecture \

systems• Living document – review frequently to ensure that it is up to

date

Team Structure

• Group responsibility – everyone holds everyone else accountable

• Have a leadership role(s) responsible for validating cleanliness

• Run code reviews or• Review check-ins on a

regular basis

Help your fellows understand the code

Documentation is a road map to cleanliness

Documentation

• Documentation is not just for you

• The process of documenting helps you better understand what really happens in the business AND in the code

• Should include:• Input / output expectations (Class & Method)• Inline logic discussions

External Documentation – Awesome !!

• Wiki or some such tool / Automated documentation generators

• Update it when you update your unit tests

• The most specific and accurate documentation is typically written by the programmers as code is written. • Flow of Execution• Code Organization• Dependencies • Class and Method Definitions

Code Documentation – Even Awesomer!

• Code documentation is generally specific to “what is going on right here”

• The intended audience is other software developers who will support the project

• Especially important when:• Doing fixes / enhancements that change original code• Gnarly code

Self Documentation – Is it a Myth?

Self-documenting code is the concept that code can be written in such a way that a human can easily understand exactly what the code is doing without added code documentation or code comments.

Self Documentation – Never Enough

Self Documentation makes several assumptions

• The reader already knows the “real” business process and already understands all the classes

• The language you use to name objects is understood by all

Process to Clean Up

• Identify bad code• Mark bad code• Make plan to remediate

bad code• Documentation of business

functionality• Create tests to validate

refactor• Refactor of code• Technical documentation

• Follow through on the plan

Cleaning up a mess

Sometimes the code gets dirty, it should get fixed

Cleaning the code up

• Always have a running system. Keep changes small and manageable• Isolate changes before making them• Make parallel algorithms

• Set up tests• Feature tests – so you can make sure everything works as you make

the changes• Performance tests – set baseline before you make changes• Load tests – if applicable

Automated Testing

• Unit Testing / Integration Testing

• While not necessary for clean code, it sure helps…

• Supports refactoring to clean up code

Questions – Comments ??

Contact

William PenberthyApplications Development ConsultantRBA, Inc.

william.penberthy@rbaconsulting.comhttp://www.linkedin.com/in/billpenberthy/