Thursday, December 27, 2007

Pro .Net 2.0 Code and Design Standards in C# - by Mark Horner

This book started great. It outlaid a structured view of how a software company should function, from the way one designs projects, to code and documentation standards. I really hoped this was the mother load: a book that would show me how a "standard" IT company functions on every level. It wasn't. Mark Horner started it well and ended it badly. A shorter book and more to the point would have been enough.

Bottom line, the book starts in an interesting way, describing what I would call "IT gap analysis", in other words the application of a simple idea: begin with a detailed (and documented) picture of what the current (start) situation is, then describe just as much detail the situation you want to reach (end). From then on, the job of describing the transition becomes orders of magnitude easier. That applies to software projects (start with what the client has and needs, then create the plan to bridge the gap), documentation (start with the functional and end with the structural) and ultimately code (start with abstract classes and interfaces, then fill in the missing code).

Other than that there are some (hopefully) nice references, then a lot of empty space filled up with irrelevant things: description of design patterns (which are nice, but there are books for something like this), a glossary of terms (some were never even used in the book!) and then the general way of describing something, then adding the "Standard acknowledges" part that basically says the same thing as his own description. It generally felt as a student paper from one that needed only a passing grade.

Sorry Mark, better luck next time. I will add here a short summary of what yours truly thought was noteworthy in the book:
  • use gap analysis for all the levels of your software work. When you define what you have and what you need, filling the blanks becomes easier.
  • use functional documentation, design documentation and structural documentation to detail what you wanted the software to do, how you designed to solve the problems and what are the basic building blocks of the project (classes, patterns, etc).
  • use code standards and peer reviews and even external code auditing to improve the quality of code. Refactoring is a must. Popular code development methodologies include Extreme Programming and Rational Unified Process.
  • use a design standard like the open-source architecture framework (TOGAF)
  • the enterprise vs. domain dichotomy. Should a software be started from scratch and done for the current set of requests only, or should it be designed as a general component ready for reuse? I would really go towards the enterprise, even when the profit from the extra work is not immediately obvious. Sometimes things that you have prepared in advance and nobody acknowledged become a real time (and life) saver when unreasonable requests tumble down upon you.
  • also linked to the enterprise/domain issue: an application framework solution. Create a basic Visual Studio solution that contains common components used in many projects and use it as a startup solution.
  • use the Visual Studio formatting options to keep your code well formatted. Use a standard of naming variables, methods, properties. My own choice is using lowerCamelCase for inner variables, prefixing the name with an underscore for fields. UpperCamelCase (or Pascal) for methods, properties and class names. Hungarian notation for controls (lbName for a label with a name). I don't really care if one names the control txtName, tbName or tboxName, as long as the prefix is revealing.
  • use the Obsolete attribute for methods and properties that are intended to be removed in the near future. In my own library I have used methods that became obsolete with the coming of .NET 2.0 and used this attribute to point not only to the obsolescence, but also to the blog entry detailing the reasoning behind it.
  • this is basically derived from other sources, but I do think it is relevant: best practices recommends using composition over inheritance, wherever possible. I admit that the coding of composition is much more complex, but with the refactoring tools found in Visual Studio and its add-ons (like my beloved Resharper), it becomes similar in complexity.
  • references:
    1. book: Programming C# by Jesse Liberty, published by O'Reilly
    2. dude: Martin Fowler is a leading authority on refactoring
    3. books to understand object-oriented development: Object-Oriented Analysis and Design with Applications by Grady Booch, published by Addison-Wesley in 1994
    4. Expert C# Business Objects by Rockford Lhotka, published by Apress in 2003
    5. book: Code Complete, by Steve McConnell, published by Microsoft Press 2004
    6. authorities on design patterns: Martin Fowler, Gregor Hohpe, Bobby Woolf
    7. dude: professor Trygve Reenskaug and his discussion on the role of object collaboration: Role Modeling and UML-VM discussions

My conclusion: read my summary and you don't waste two days of reading time.