About Craftsmanship

Nuway is committed to bringing craftsmanship and raising the bar in the profession. Below we describe how we believe software should be written. We unashamedly share our opinion of what is wrong within our industry. However, criticism without care for solutions is of no more benefit than a clanging gong or a crashing symbol: it's loud and annoying to everyone.

Many clients want to outsource a single project, but take over the support and future changes when it is completed. In this case the quality of the code and its ability to be easily understood by new people is of utmost importance. A vendor who may be the cheapest up front may cost tens or even hundreds of thousands of dollars later in wasted time and effort as the receiving team tries to understand the code, or spends time replacing poorly written parts.

What we mean by Craftsmanship

Craftsmanship is the fusion of attitude and competency.

Attitude is one's personal motivation to doing their best. Craftsmanship takes effort. Craftsmanship requires discipline. The right attitude fuels the hard climb necessary to learn improved ways of doing things. Some people want to do well, but never put in the effort. In this case their actions betray their true mind-set.

Competency is one's ability or skill in a field. Competency comes from many paths: natural talent, education, trial and error, and experience over time. Regardless of how it comes, competency is the extent of control someone has on achieving their desired result. Someone may desperately want to play Mozart on the piano, but if they haven't taken any lessons, the goal is simply out of grasp.

The mark of a craftsman is someone with a wealth of experience, demonstrated ability, and a strong desire to do better next time.

Why Craftsmanship Counts

Software construction is a continual process of choosing one way forward from dozens (or hundreds) of possibilities. All of these choices stack and ultimately become the finished product. A person with the right attitude will evaluate many paths before deciding the best one. The first readily apparent answer is often the wrong one. A person with high competency knows of many more possible paths and which ones are dead ends.

The two major places where craftsmanship counts are performance and extendibility.

Well crafted software runs fast. There is no "bloat" of useless processing or unnecessary calculations. For instance, looking up information in a database can be done once or require several round trips. The many round trips could be 50x slower, but it is easier to program. When many shortcuts like this are taken the software suddenly only runs on high-end hardware, or doesn't allow remote users to work effectively. Now poor craftsmanship is costing the client money.

Well crafted code is easy to change and extend, even by someone who didn't previously work on the system. When all of the classes in the code have meaningful names and follow proper rules of encapsulation, it's a quick and pleasurable experience to add additional functionality. If the code resembles "spaghetti" it will take a long time to make the change and squash all the resulting bugs. Now poor craftsmanship is costing the client money in unnecessary effort.

The Right way to Write Code

Object Oriented Programming (OOP) through Design Patterns¹

Most, if not all, programming tasks can be boiled down to a generic problem. It is likely these generic problems have already been solved. The solution to a generic programming problem is called a Design Pattern. The use of design patterns ensures you are solving a problem correctly, in a way that will scale, and you won't run into unforeseen roadblocks in the future.

Self-Documenting Code²

Nuway writes clean code. Code that self-documents as much as possible. In practice this looks like:

1. Routine names describe exactly what the routine does, with VerbNoun naming convention.
2. Each routine performs one well-defined task. If a routine does only one thing, it's easy to find a problem or know where to make a change.
3. Variable names are descriptive of the business value they contain, not things like: var, val, i, j, etc.
4. Special values are enumerated or stored as constants instead of "magic numbers".
   • Size == PizzaSize.Large is clearer than Size == 12

Code Comments³

When code isn't clear through self-documenting (see above), Nuway provides the relevant comments. This is quality, not quantity. We abide by the following principles when commenting:

1. Clarify the intent of the code, don't explain what it does
2. Whenever a decision is being made in the code, explain why
3. Document any specialized knowledge.
   • If an external API requires calling two methods in a particular order to work this must be captured for future reference when someone is doing maintenance.
4. Comment anything that gets around an error or an undocumented feature in a language or environment
   • If you've discovered a TCP listening routine doesn't handle exactly 1025 bytes, but all other values are fine, make a note of it
5. If utilizing a Design Pattern, document which one it is and where it came from (GOF, MSDN, Etc.)

Refactoring⁴

Typically your first attempt at something is never your best. A second pass will typically show better ways of accomplishing the same goal. Rewriting your code a second time is called refactoring. This isn't something left to the end "when I have time", it's part of the process. You refactor as you go. The rules used in refactoring are extensive, but the reason Nuway practices it are:

1. Improves the design of software
2. Makes software easier to understand
3. Helps you find bugs
4. Helps you program faster

Notation

Nuway follows the Microsoft standards for programming notation. The purpose is to make the software code look as much like Microsoft's so you don't have to switch mental gears as you read

1. In C#, we use camel case notation ⁵
2. In C++ we use Hungarian notation ⁶

Test Driven Design ⁷

The most expensive part of a software change is the verification the change didn't break anything. This verification is called Regression Testing. Test Driven Design eliminates the need for regression testing, thereby flattening the cost of change.

The process was popularized by the agile development process eXtreme Programming (XP). Test driven design means the programmers write automated tests that check the code to make certain it is still correct. As the team builds the total project, all the individual tests build up into an extensive arsenal of tests that can very quickly guarantee the entire system is operating correctly. This is critical to reducing the cost of changes in the future. Now a change can be made, the automated tests run, and the integrity of the system verified without copious amounts of manual labour.

Documentation

Following the UP generates a lot of working documentation. All this documentation is in UML , the industry standard notation. Our documentation includes:

1. Use Case diagrams - to show stake holder ownership and system scope
2. Activity Diagrams - to show complex business rule branching
3. Class Diagrams - to show system design and interaction
4. Sequence Diagrams - to show per use case message flow

Sources

1. 1 Erich Gamma, Richard Helms, Ralph Johnson, and John Vlissides, Design Patterns: Elements of Reusable Object-Oriented Software, Addison Wesley, 1995.
2. 2 Steve McConnell, Code Complete, Microsoft Press, 1993, 456.
3. 3 Steve McConnell, Code Complete, Microsoft Press, 1993, 488.
4. 4 Martin Fowler, Refactoring: Improving the Design of Existing Code, Addison Wesley Longman, 1999.
5. 5 "Naming Guidelines", .NET Framework General Reference, MSDN, 2005.
6. 6 "Variable Names and Hungarian Notation", MSDN, 1998.
7. 7 Kent Beck, eXtreme Programming, Addison Wesley, 2000.