Tuesday, October 20, 2015

Design Patterns

What is a Design Pattern?

A design pattern is a re-usable form of a solution to a design problem.  It helps us by not having to re-invent the wheel when we design and code solutions.  

Finding the right fit is crucial:  A) Using the wrong pattern for a problem can cause more problems; and B) Using a pattern for a trivial problem is overkill and, thus, costly.  Along this line, there is a term, anti-pattern, for a common response to a recurring problem that is typically ineffective and counterproductive.

It is my opinion that the patterns need not be memorized.  What is most important that their concepts be understood enough to know when they should be applied.  It is useful to review the various explanations and code samples when beginning a new design with a fresh perspective.  They also come in very handy when refactoring existing code.

So as not to reinvent the wheel myself, please see the following references for more information.

Where are some Good References?

Saturday, September 12, 2015

All Hail the README File!

What is a readme file?  It is a text file that helps other developers know how to do things with your software project that aren't obvious like:
  • Special build instructions
  • Third-party package descriptions
  • Where to find the associated technical documentation or official software development procedures
  • How build the API documentation
  • How to run a code analysis
  • TDD procedures
The goal of the readme file is to keep it short and sweet.  Provide just enough information to help the developer know how to work with the software project.

What are the contents of a good readme file?  Your readme file's content depends on the nature of your project.  Here are some some examples:
  • If you are writing software that is only going to be modified in-house or as an open-source project, it makes sense to include a topic like How to get the latest version from source code control.
  • If you are delivering a software package, it is useful to include topics like How to install and Getting Started.
  • If you are delivering a web service API, a good topic could be How to authenticate your client.

What are the benefits of a readme file?  There are quite a few benefits:
  • The file can be quickly created and maintained even in software shops that hold little regard for documentation or the software development process.
  • All current and future developers will have a single source of helpful information right at their fingertips, right alongside the code.  This saves a LOT of time (and we all know that time = money) and frustration.
  • It enables one to see when a procedure is getting overly complicated and in need of refinement and simplification.
  • It provides a talking point for discussion.

How does one name a readme file?  README.TXT, README, readme, readme.html, readme.txt, or _readme.txt.  Depending on your operating system and the tool/command you are using to view your files, the highlighted names are typically used to cause the file to appear close to the top of the list of files.

When should we create the readme file? Ideally before any code is written.  This helps the author plan and think about how to structure the project(s).

What are some other possible uses?  For those using .Net, a project-specific readme file can be used for each project instead of one readme file for your entire solution (.sln).  A project can be used in one or more solutions.  A project-specific readme file lets one record important details about the project, whereas a solution-specific readme file can be placed in a Solution Files folder at the top of the solution.  For example:

What is a good example of a readme file? My favorite is to have a table of contents that the reader can easily skim, copy the topic string to the clipboard, then do a 'find' pasting in the topic name to locate the details of the topic.  This is shown below:

    PROJECT-X DEVELOPMENT README FILE

    *** TABLE OF CONTENTS ***
    WHAT IS THIS PROJECT?

    WHERE IS THE CODE LOCATED (FOR XYZ EMPLOYEES ONLY)
    ITEMS NEEDED

    HOW TO BUILD (COMPILE)
    HOW TO ADD A NEW PROJECT
    TROUBLESHOOTING
    CODING STANDARDS


    *** DETAILS ***

    WHAT IS THIS PROJECT?

       etc. 

Other sources:

Why I wrote this blog post:  As a software consultant, most software projects I have seen either have no readme file or one so huge it is difficult to maintain.  The latter point indicating the software project might possibly be overly complicated, or perhaps it is so large that each module warrants its own readme file.