Monday, April 16, 2018

ASP.Net Core 2 with Postgresql on Linux Part 7: The Service Layer

In Part I, I discussed the rationale for porting a ASP.Net Core 2 app to my Linux system replacing SQL Server with Postgresql and place it on Heroku. 

With Part II, we transferred the SQL Server data to Postgres.


In Part III, I create the ASP.Net MVC Core 2.x app, from which we will proceed, and get Entity Framework Core installed.


Then in Part IV, I look at the configuration differences between the ASP.Net MVC app that uses SQL Server and the new app, in preparation of porting the old app to use Postgresql.

Part V, we compared the differences in both the projects' structures and ported the existing project code, starting with the data model layer, to the new project. In addition to this, we got the jquery.countdown jquery plugin installed, that is used to implement a JavaScript timer. More on that in a later article. Finally, we used the dotnet ef dbcontext scaffold command that builds a DbContext and entity types for out Postgresql database. And, oh yes, we added the project to github, which frankly should have been done day one.


In Part VI, we got the NUnit testing framework in place 
in order to test both the new and future code.


In this post, we will get the Service layer setup in order to unit test which will test the Data and Model tiers as well.

Using the Beyond Compare tool, let's look at the differences between the existing ASP.Net MVC app and the new project concerning the Service tier:



As you can see, there are no Service classes in the right side, which is the new app, of the folder-level comparison. 

Instead of simply copying all the Service layer code to the new app with Beyond Compare, let's add one class at a time, setting up unit test for each one. 

The first one we will copy is the EsvService.cs class. Also, you will note that in the above image, there is a IEsvService.cs file as well as EsvService. The IEsvService is an interface class. Here is a section of code from the EsvService.cs file:

  public class EsvService : ServiceBase, IEsvService  
 {  
      private static string ApiKey  
      {  
        get { return "myKey"; }  
      }  
      private static DateTime TodaysDate  
      {  
        get { return GetESTDate(); }  
      }  
 //......  
 }  

Here is the updated code that contains the interface class as well as the implementation:


  public interface IEsvService  
 {  
      Task<string> GetVerseAsync(string verseReference);  
      Task<string> GetDailyVerseAsync();  
      Task<string> GetTodaysPsalmAsync();  
 }  
 public class EsvService: ServiceBase, IEsvService  
      {  
      private static string ApiKey  
      {  
        get { return "myKey"; }  
      }  
      private static DateTime TodaysDate  
      {  
        get { return GetESTDate(); }  
      }  
 //...       
 }  

I find this easier to manage when changes are made to the interface since you are already in the correct location to update the implementation class, EsvService, in this case. Also, you will note that the class implements the ServiceBase class. Therefore, I will move that to the new app as well. After updating the namespace in the new code, the project compiled and all is well.

At any time if you want to view the source code, go here.

Next, let's get a reference set to the myApp project from the UnitTest project.


 $ dotnet add reference ../myApp/myApp.csproj  


After adding the myApp project, which is the system under test (SUT), I added a few test methods:



Then, as you can see from above, I issued the dotnet test command and all passed. 

However, we really do not want to run tests we are depending on outside resources each time. While that type of test is valuable, it is what is referred to as an integration test and should only be run as needed. Here, we just want to test our code and not the dependencies. Enter, Moq, the mock testing framework that helps you mock or fake the dependencies and just tests your code.


 $ dotnet add package Moq  




Then, I updated the existing Service test methods and moved integration tests to a separate class. In order to run the standard mocked unit tests separately, I employed NUnit's Category Attribute.




Then, I ran dotnet test --filter TestCategory=Unit, and here is the result:




After this, I ported the remaining Service classes from the existing ASP.Net MVC app to this one. Looking at the comparison there are several classes that were moved.

As I mentioned above, I moved the interface classes into the same file as their implementation classes. Therefore, the classes starting with "I" are not in the new app.

Now that we have the Data, Model, and Service layer classes ported, next in Part VIII, we will import the Controller classes from the existing to the app and setup unit tests for them.



Monday, April 09, 2018

ASP.Net Core 2 with Postgresql on Linux Part 6: Setting up Unit Testing

In In Part I, I discussed the rationale for porting a ASP.Net Core 2 app to my Linux system replacing SQL Server with Postgresql and place it on Heroku. 

With Part II, we transferred the SQL Server data to Postgres.


In Part III, I create the ASP.Net MVC Core 2.x app, from which we will proceed, and get Entity Framework Core installed.


Then in Part IV, I look at the configuration differences between the ASP.Net MVC app that uses SQL Server and the new app, in preparation of porting the old app to use Postgresql.

Part V, we compared the differences in both the projects' structures and ported the existing project code, starting with the data model layer, to the new project. In addition to this, we got the jquery.countdown jquery plugin installed, that is used to implement a JavaScript timer. More on that in a later article. Finally, we used the dotnet ef dbcontext scaffold command that builds a DbContext and entity types for out Postgresql database. And, oh yes, we added the project to github, which frankly should have been done day one.

In this post, Part VI, it would be best to get a unit testing framework in place
in order to test both the new and future code.

First, let's create a new unit test project. I have found that it is best to separate the csproj files so I have created a new folder. So from a separate folder than the myApp folder I issued the following command:


 $ dotnet new classlib -n UnitTests  


Here is the output



Using the new Multi-root workspace feature, I was able to add the new UnitTests project to thew view in VS Code:


Next, within the new UnitTest project folder,  I issued the following in the unit test project directory:


 $ dotnet add package NUnit  


After that:


 $ dotnet add package Microsoft.NET.Test.Sdk  


Then:


 $ dotnet add package NUnit.Console  




The final command to get all the NUnit packages installed was:


 $ dotnet add package NUnit3TestAdapter  


I issued the dotnet restore to make sure that everything was up to date. When doing that I noted the following error:



I then noted that the target framework was not the standard and not the core framework:



After updating the TargetFramework setting to netcoreapp2.0 and running dotnet restore, it was good.

One thing I noted with working with the multi-root workspace feature, the C# extension settings did not take effect until I closed VS Code, opened the new UnitTest project in VS Code by itself, rebuilt the project, closed it, and then re-opened the multi-root workspace.

Next, step was to create an NUnit test to simply test that the NUnit packages are setup properly. This seemed appropriate:



I then invoked the dotnet test command and all is well:



In Part VII, we will get the Service layer setup in order to unit test it as well as the Data and Model tiers.


Monday, April 02, 2018

ASP.Net Core 2 with Postgresql on Linux Part 5: Data Model Layer, Etc.

In In Part I, I discussed the rationale for porting a ASP.Net Core 2 app to my Linux system replacing SQL Server with Postgresql and place it on Heroku. 

With Part II, we transferred the SQL Server data to Postgres.

In Part III, I create the ASP.Net MVC Core 2.x app, from which we will proceed, and get Entity Framework Core installed.


Then in Part IV, I look at the configuration differences between the ASP.Net MVC app that uses SQL Server and the new app, in preparation of porting the old app to use Postgresql.


Here in Part V, we will start comparing the differences in both the projects' structures and porting the existing project code, starting with the data model layer, to the new project.

Since the next step is to look at the existing Windows ASP.Net MVC app using SQL Server and to move it to a Linux system with Postgresql, I thought it best to first look at what the overall differences are in the two projects.




So, using Beyond Compare, as mentioned in the previous post, to look at the differences in the folder structure, here are my initial observations.

First, note that there is a bower package component folder that is not present in the new app. Within the folder bower_components folder you see jquery.countdown. As per their site, they state to use the following to install:



 $ bower install jquery.countdown  

While their github page offers other installation methods via npm, et al, bower is still solid. However, even bower is encouraging a move to yarn...yet bower is still being maintained. 

Looking at further differences, there is a Data folder with Entity Framework Core classes as well as classes that implement them.


Then, I copied the Entity Framework Core classes as well as the implementation classes to a Data folder in myApp. 


Of course, this will not be useful until the controller and view objects are ported as well. Meanwhile, I will get unit tests for the the data model layer...more on this later.

So, given the fact that, as found above, that bower is encouraging a move to yarn, it seems prudent to make that move for this app now. Per Yarn's site, here is what I did:

 $ curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -  
 $ echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list  
 $ sudo apt-get update && sudo apt-get install yarn  

Next, I attempted to install jquery.countdown via yarn with:

 $ yarn install jquery.countdown  

The result was the following:

 yarn install v1.5.1  
 info No lockfile found.  
 error An unexpected error occurred: "`install` has been replaced with `add` to add new dependencies. Run \"yarn add jquery.countdown\" instead.".  
 info If you think this is a bug, please open a bug report with the information provided in "/home/mark/Code/dotnetcore/myApp/yarn-error.log".  
 info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.  


So, per the above instructions:


We will test the install jquery.countdown later, meanwhile let's try to build the myApp project.

As expected, there are things missing and the build fails.


Given that we have just ported classes that have a different name space as well as references to objects that are not in the project, we have a great deal of red text above. Now to make the corrections.

First, I replaced the old reference to the m2prayerVS2017NetCore.Models name space with myApp.Models in each of the migrated Entity Framework Core classes. Also, the Migrations folder were from the previous project and not needed here. 

After commenting the Entity Framework Core code that was calling into missing model files, I issued the following command to get the model objects scaffolded from the Postgres database:

 $ dotnet ef dbcontext scaffold "Host=localhost;Database=postgres;Username=youUserName;Password=yourPassword" Npgsql.EntityFrameworkCore.PostgreSQL -o Models  


Then, I uncommented the Entity Framework Core code and corrected for the lower-case use of table names that are conventional with Postgresql. For example, while SQL Server will have a table named AspNetUsers, Postgres' naming convention entitles it aspnetusers.



Yet, when attempting to build, I found that I was missing the ApplicationUser class from the Models namespace. 



After copying it from the old ASP.Net app and updating the namespace name, the project would then build.

Oh my, I just realized that we do not have this project in any kind of source control! Let's take care of that right now. Essentially, I followed the steps here.

Given that the Entity Framework Core data classes have been moved to the myApp application and the model objects scaffolded, creating unit tests utilizing them is the next step. Therefore, in Part VI we will look at setting up unit testing in order to test both the new and future code.





Monday, March 26, 2018

ASP.Net Core 2 with Postgresql on Linux Part 4: Sync Configuration Differences


In In Part I, I discussed the rationale for porting a ASP.Net Core 2 app to my Linux system replacing SQL Server with Postgresql and place it on Heroku. In Part II, we transferred the SQL Server data to Postgres.

In Part III, I create the ASP.Net MVC Core 2.x app, from which we will proceed, and get Entity Framework Core installed.

Next, in Part IV, I look at the configuration differences between the ASP.Net MVC app that uses SQL Server and the new app, in preparation of porting the old app to use Postgresql.

First, let's look at the existing app's project file and compare that to the one that we have in our new app that use Postgresql. Of course, in order to do that we will need the code from the app using SQL Server. To do that, I cloned my existing Windows based ASP.Net MVC .Net Core project onto my Linux system as I will be reusing a good deal of the code moving forward. Here is what I did (For more information see: https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository):


 $mkdir WinCoreProject  
 $cd WinCoreProject  
 $git clone https://myUserName@bitbucket.org/myUserName/myASPNetCoreApp.git  

Now that we have the code from the existing app, let's compare the two project's config files, which are in the root directory of each projects' folder. 

One of my favorite tools for this task is a multi-platform, data comparison utility called Beyond Compare. Comparing the two project files, here is a look at the differences.


Note the text in red in the right side of the view. This shows that the old app's configuration includes three additional settings. The NetCore.MailKit entry is for a MailKit extension for asp.net core that I use to send a confirmation email to users who want to create a user account. Serilog is a logging library with many nice features. In addition, we see the Serilog.Sinks.RollingFile package setting that allows for a daily log file entries.

To sync the two files, let's continue with Beyond Compare. Select the yellow arrows in the right pane to move the text to the config file displayed in the left pane.




Then, to update the myApp.csproj file, select the disk icon to the right of the project file name.


Here is the view of the synced files:


Next, run the dotnet restore command at the command prompt to install the packages:

$dotnet restore   

Note that you can also install the packages at the command prompt in the application's root directory:  
 $dotnet add package NETCore.MailKit

Per the location here, "The dotnet add package command provides a convenient option to add a package reference to a project file. After running the command, there's a compatibility check to ensure the package is compatible with the frameworks in the project. If the check passes, a <PackageReference> element is added to the project file and dotnet restore is run." 

Visual Studio Code, with the C# extension, will also assist you when you update the project file. 


In the next post, Part V, we will start comparing the differences in both the projects' structures and porting the existing project code, starting with the data model layer, to the new project.


Friday, March 23, 2018

ASP.Net Core 2 with Postgresql on Linux Part 3: Create the ASP.Net MVC Core 2.x app and Install Entity Framework Core

In Part I, I discussed the rationale for porting a ASP.Net Core 2 app to my Linux system replacing SQL Server with Postgresql and place it on Heroku. As I thought about it, my first logical step was to port the data from SQL Server to Postgresql. While I think I am proficient at the command prompt, I had to admit that having a GUI based tool would be a help. Having used pgAdmin on a Rails 3.x project, that is where I leaned. In that article I show the steps to installing pgAdmin, a GUI Postgresql client on Ubuntu 16.04. In Part II, we transferred the SQL Server data to Postgres.

In this post, I create the ASP.Net MVC Core 2.x app, from which we will proceed, and get Entity Framework Core installed.

First, I created a new ASP.Net MVC .Net Core C# project in Visual Studio Code (see https://docs.microsoft.com/en-us/aspnet/core/tutorials/first-mvc-app-xplat/start-mvc for more).

 $mkdir myApp  
 $cd myApp  
 $dotnet new mvc  

I already had the .NET Core 2.0.0 SDK, Visual Studio Code, and the VS Code C# extension on my Ubuntu 16.04 Linux system. See https://docs.microsoft.com/en-us/aspnet/core/tutorials/first-mvc-app-xplat/start-mvc for more information on these steps.


Then, I issued a dotnet run to build and execute the source code:


Per the URL provided in Visual Studio Code screen above, I browsed to http:/localhost:5000:


OK, so the app will build and load.

Next, I updated the project file in Visual Studio Code (myApp.csproj) to include the following settings to install Entity Framework Core:

 <Project Sdk="Microsoft.NET.Sdk.Web">  
  <PropertyGroup>  
   <TargetFramework>netcoreapp2.0</TargetFramework>  
  </PropertyGroup>  
  <ItemGroup>  
   <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.5" />  
   <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="2.0.0" />  
  </ItemGroup>  
  <ItemGroup> 
    <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.2" />  
    <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools" Version="2.0.0" />  
    <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="2.0.0" />  
  </ItemGroup>  
 </Project>  

Then, I ran the dotnet restore command to install the above EF package and tools:

 $dotnet restore  


Now we have a working ASP.Net MVC Core 2.0 app with Entity Framework Core installed.

Next, in Part IV, I look at the configuration differences, in preparation of porting my existing app to use Postgresql.


Tuesday, March 20, 2018

ASP.Net Core 2 with Postgresql on Linux Part 2: Move SQL Server Data to Postgres

In Part I, I discussed  the goal of porting my ASP.Net Core 2 app to my Linux system using  Postgresql as the database and placing it on Heroku. As I thought about it, my first logical step was to port the data from SQL Server to Postgresql.

While I think I am proficient at the command prompt, I had to admit that having a GUI based tool would be a help. Therefore, Part I details the setup of pgAdmin installed on my Ubuntu system.

Here, in Part II we port the existing SQL Server data to Postgres.

First, I looked around for a free tool to take an existing MS SQL database and transfer it to a Postgresql database. However, what I found did not seem to meet my goal. Given the disparity between the Db platforms, the best tool I could find was a Postgresql function entitled convert_mssqlddl2pgsql.sql. Since I had existing MS SQL Create Table scripts already, this seemed the best option.

In short, I loaded the convert_mssqlddl2pgsql script into pgAdmin and added my MS SQL Create Table script (for each existing table, one at a time) as the input parameter (see below), and the output was a Postgres Create Table script.



Here is the SQL for the SQL Server table
 CREATE TABLE [dbo].[myTable](  
   [myID] [int] IDENTITY(1,1) NOT NULL,  
   [FirstValue] [varchar](50) COLLATE SQL_Latin1_General_CP1_CI_AS NULL,  
   [SecondValue] [varchar](50) COLLATE SQL_Latin1_General_CP1_CI_AS NULL,  
   [ThirdValue] [varchar](50) COLLATE SQL_Latin1_General_CP1_CI_AS NULL,  
  CONSTRAINT [PK_MyID] PRIMARY KEY CLUSTERED   
 (  
   [ContactID] ASC  
 )WITH (IGNORE_DUP_KEY = OFF) ON [PRIMARY]  
 ) ON [PRIMARY]  
re is the Data Output from pgAdmin function above:


 create table public.mytable(  
   myid serial not null,  
   firstvalue varchar(50) null,  
   secondvalue varchar(50) null,  
   thirdvalue varchar(50) null,  
  constraint pk_myid primary key   
 (  
   myid  
 )   
 )                  

After running the pgAdmin function for each SQL Server database table and then running the script in pgAdmin to create the Postgres database tables, I made sure that the sequence columns were set accordingly. To do this I ran the following for each table with a serial id column:

 UPDATE public.mytable SET myid=nextval('mytable_myid_seq');  

You can use pgAdmin to check the serial id columns to may sure that the default value property of the column is set to the next available value.



The next step was to get the data from the MS SQL database tables into the newly formed Postgresql tables. What I did was to get a record-by-record text file output of the SQL Server table from a select statement that consisted of the table values.
 'Your first column value here', 'Your second column value here...','and you guest it....your third column here!'  
 'Your first column value here again', 'Your second column value here..yeah...','and your third column here!'  
 'Your first column value here, one more time', 'Your second value','your third column!'  

Now that I had the SQL Server table data into a fixed length format, the next step was to transform it into proper Postgres insert statements.

Mind you, I know that I could have used a SQL select statement within SQL Server to create the Postgres insert statements, but given that I have been a Ruby fan from way back and reading in and parsing files is one of the strengths of Ruby, the next step was a natural evolution, or at least some kind of semi-intelligent design...I used the Ruby script below to produce the Postgres insert scripts.

 file = File.open("myValues.txt", 'r')  
 while !file.eof?  
   line = file.readline  
   puts "INSERT INTO public.tableName(firstColumn, secondColumn, thirdYouGuestItColumn) VALUES ( " + line + ");"  
 end  

The output was the following:

 INSERT INTO public.myTable(  
      firstvalue, secondvalue, thirdvalue)  
      VALUES ('Your first column value here', 'Your second column value here...', 'and you guest it....your third column here!');  
 INSERT INTO public.myTable(  
      firstvalue, secondvalue, thirdvalue)  
      VALUES ('Your first column value here again', 'Your second column value here..yeah...', 'and your third column here!');  
 INSERT INTO public.myTable(  
      firstvalue, secondvalue, thirdvalue)  
      VALUES ('Your first column value here, one more time', 'Your second value', 'your third column!');  

Just as before, I ran the above script in the pgAdmin client. The result was Postgresql tables with data!

In short, these are the steps that took place with each table.

Now that my data is in Postgresql, the next step, to be detailed in Part III, I create the ASP.Net MVC Core 2.x app, from which we will proceed, and get Entity Framework installed.


Thursday, March 15, 2018

ASP.Net Core 2 with Postgresql on Linux Part 1: Installing pgAdmin4 on Ubuntu 16.04

For the last 15 years I have had a personal web-based app that I have used to learn new languages and frameworks. 

Starting with Microsoft's .Net 2.0 framework and then moving from Ruby on Rails 3.x, to MeteorJS, and then to .Net Core 1.x, this app has also been used with MySql, SQL Server, MongoDb, and Postgresql as the data access layer. 

Currently, I have ported the app to ASP.Net Core 2 with SQL Server on the Azure cloud. As I was poking around my github repo I thought why not use my Linux Ubuntu 16.04 laptop and port the current ASP.Net Core 2 app to my Linux with Postgresql and place it on Heroku? 

As I thought about it, my first logical step was to port the data from SQL Server to Postgresql. While I think I am proficient at the command prompt, I had to admit that having a GUI based tool would be a help. Having used pgAdmin on my Rails 3.x project, that is where I leaned. So, step one, get pgAdmin installed on my Ubuntu system. 

Thanks to the data from https://askubuntu.com/questions/831262/how-to-install-pgadmin-4-in-desktop-mode-on-ubuntu, this was a much easier transition. 

Here is what I did:

Installed pgAdmin4 using Python3.x (I preferred to avoid encoding related issues):
 $sudo apt-get install virtualenv python3-pip libpq-dev python3-dev  
 $cd  
 $virtualenv -p python3 pgadmin4  
 $cd pgadmin4  
 $source bin/activate  
 $pip3 install https://ftp.postgresql.org/pub/pgadmin/pgadmin4/v2.1/pip/pgadmin4-2.1-py2.py3-none-any.whl  
 $gedit lib/python3.x/site-packages/pgadmin4/config_local.py  

Copied this to the config_local.py file:
 import os  
 DATA_DIR = os.path.realpath(os.path.expanduser(u'~/.pgadmin/'))  
 LOG_FILE = os.path.join(DATA_DIR, 'pgadmin4.log')  
 SQLITE_PATH = os.path.join(DATA_DIR, 'pgadmin4.db')  
 SESSION_DB_PATH = os.path.join(DATA_DIR, 'sessions')  
 STORAGE_DIR = os.path.join(DATA_DIR, 'storage')  
 SERVER_MODE = False  

Created the following directories and change the permissions:
 $sudo mkdir "/var/log/pgadmin"  
 $sudo chmod a+wrx "/var/log/pgadmin"  
 $sudo mkdir "/var/lib/pgadmin"  
 $sudo chmod a+wrx "/var/lib/pgadmin"  

Created a file in my /home/mark folder named pgAdmin4.py and copy this to the file (note that your user name will be the folder here):
 #!/bin/bash  
 cd ~/pgadmin4  
 source bin/activate  
 python3 lib/python3.5/site-packages/pgadmin4/pgAdmin4.py  

Made the file executable:
 $chmod +x /home/mark/pgAdmin4.py  

Then, I installed postgres locally. First I created the file /etc/apt/sources.list.d/pgdg.list, and added a line for the repository:
 deb http://apt.postgresql.org/pub/repos/apt/ xenial-pgdg main  

I imported the repository signing key, and update the package lists:
 $wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | \  
  sudo apt-key add -  
 $sudo apt-get update  

Next, I installed PostgreSQL on Ubuntu, using the apt-get (or other apt-driving) command:
 $apt-get install postgresql  

Finally, after the install of postgresql, I created a user and give them permissions:
 $su -s  
 $su - postgres  
 $psql  
 postgres=# CREATE USER yourUser PASSWORD 'userPassword';  
 postgres=# GRANT ALL ON SCHEMA test TO yourUser;  
 postgres=# GRANT ALL ON ALL TABLES IN SCHEMA test TO yourUser;  
 postgres=# \q  

Now, when I run the ./pgAdmin.py command from a terminal and navigate to http://127.0.0.1:5050/browser/ in my web browser, I see the following:

In Part 2, I will detail the process of moving the data from SQL Server to Postgresql.

Thursday, March 08, 2018

Selling Out has been Amazing!


I have been delving into the world of Docker and Containers on both Linux and Microsoft Windows. I was listening to a podcast that recommended the Youtube video, "Containers aka crazy user space fun" that records Jessie Frazelle's keynote at Linux Conf in Australia. At about 1:50 into the video she stated, "who am I?...I work at Microsoft...selling out has been amazing!" There was laughter from this Linux crowd and she continued on to give a great and informative talk on Linux Containers. Typically, selling out is a bad thing and Jessie Frazelle obviously did not mean it in a negative way. On a side note I love that Microsoft loves Linux and I am sure that has resulted in a great working experience for Jessie. Contrary to the populist view that all corporations are evil, this goes to show that companies can...and some do change.

Monday, February 26, 2018

When All Else Fails... Where's the Manual?

How many times have you purchased a product and it required some sort of assembly? You try to put it together only to find you have extra parts left over. As a last resort, you look for the manual. What about when you have to repair it or modify your purchase? Where is the manual?

Concerning software development, if you have a piece of code...a class, a library, or a database table and no one knows who owns it (a.k.a. who created it, is responsible for maintenance, and/or is the source of knowledge for that machine) and something needs to change, either moving to a new system, new feature added, etc, then you have a problem. What typically ensues is similar to what takes place on a factory floor when a piece of equipment that has been running for some time on a production line with out issue needs fixed or new functionality added. 

First, an inquiry is made to the maintenance team asking who is responsible for its upkeep. However, what is found is the maintenance personnel that once created the machine, did the upkeep, and the addition of new functionality is no longer with the company. Then, the maintenance team will review the equipment manual (think dev team documentation here for this analogy). If there is none (which unfortunately is the common case with software that is produced by many dev teams), the team has to consider a few options.

Should they reverse engineer the machine and create a new one? What about simply making the needed changes to the current piece of equipment and risk breaking it? As you know from experience or can imagine, each option has its pros and cons. Yet, wouldn't it be better to have some documentation available to assist? This is why, in my view, documentation is so important when creating software.

Do yourself and others a favor and document with both informative comments in your code as well as external documentation explaining the business rationale as well as a description of your interfaces and objects. 

Saturday, February 10, 2018

Niall Ferguson, author of The Square and the Tower, on TWiT's Triangulation show

Just listened to Niall Ferguson, author of The Square and the Tower, on TWiT's Triangulation show. Yet another reason that the Humanities in general and History specifically is vital in any well rounded education.