DEV Community: Dalbir Singh

Clean Code – Part 2

Dalbir Singh — Wed, 02 Sep 2020 18:32:53 +0000

It’s time for the second installment of ‘Clean Code’. If you missed the first one you can find it here:

Article No Longer Available

Principle of Proximity

This principle is based on ‘tell me what I need to know - when I need to know‘. I see new developers often caught up adding many unrelated variables to the top of their methods.

Adding properties and backing variables to the top of a class definition is fine. However, when it comes to method implementations, following the same approach can lead to readability issues.

Take for instance the code below. It contains a method which generates an invoice document and then emails it to the customer:

var smtpHost = AppSettingsHelper.GetSmtpHost();
var from = AppSettingsHelper.GetFromMailAddress();
var subject = "Your bill is ready.";
var to = AppSettingsHelper.GetToMailAddress();
var billableItems = _billingService.GetBillForUser(userId);

//
// long lines of code here to generate a pdf file with 
// the invoice details...
//
// var invoice = ...
//

// send email with invoice as attachment
var ms = new MemoryStream(Encoding.GetBytes(invoice));
var attachment = new Attachment(ms, "Invoice.xml");  

var body = $"Hi, here is your invoice blah blah... "

using (SmtpClient client = new SmtpClient(smtpHost)
{
  var message = new MailMessage(from, to, subject, body);   
  message.Attachments.Add(attachment);

  client.Send(message);
}

Imagine yourself or another developer coming back to this code six months later. There are a lot of variables to comprehend, and most of those are largely unrelated to the proceeding code.

Here’s a better structure:

var billableItems = _billingService.GetBillForUser(userId);

//
// long lines of code here to generate a pdf file with 
// the invoice details...
//
// var invoice = ...
//

// send email with invoice as attachment

var smtpHost = AppSettingsHelper.GetSmtpHost();
var from = AppSettingsHelper.GetFromMailAddress();
var subject = "Your bill is ready.";
var to = AppSettingsHelper.GetToMailAddress();

var body = $"Hi, here is your invoice blah blah... "

using (SmtpClient client = new SmtpClient(smtpHost)
{
  var message = new MailMessage(from, to, subject, body);  
  var ms = new MemoryStream(Encoding.GetBytes(invoice));
  var attachment = new Attachment(ms, "Invoice.xml");  

  message.Attachments.Add(attachment);
  client.Send(message);
}

Much better. Now when reading the code you only need to comprehend the variables relating to the proceeding code. For example, the email related variables are kept around the email creation logic.

Refactoring is good – just don’t overdo it.

The readability of the sample code above can be further improved by moving significant portions of work to their own methods. This also helps when debugging by making it much easier to pinpoint where errors may be occurring. New developers benefit too, by helping them understand “what the code is trying to do” without being bogged down by noise in “how” it is doing it.

try
{
  var user = GetUser(userId);

  var billableItems = _billingService.GetBillForUser(userId);

  var invoice = GenerateInvoice(user, billableItems);

  EmailInvoice(user, invoice);
}
catch(Exception)
{
  // handle exception
}

When refactored correctly, code should be “easy” to read and not require so many comments. Note that overzealous refactoring can also cause harm. Extracting code to methods excessively causes inefficiency as the developer scrambles through the codebase to find bits of code.

Enums in place of comments

As developers, we often fall into the trap of using raw integer values directly in code. I’ve mentioned before about storing such values in a database or configuration file, though for data values that are unlikely to change this could be overkill. In those cases, using integers in the code is the preferred choice.

For example, let us imagine a ‘status’ method on an entity…

device.setStatus(1);    // 0 = disabled, 1 = enabled, 2 = hybrid

Using a boolean value is not sufficient in this example as there three possible states. In this case, using integers makes sense, but this causes two problems with readability:

A reliance on comments for describing values. Not everyone writes helpful comments.
Duplication of comments. Comments describing values in this way are likely to be copied and pasted across the codebase where similar code exists. Even worse, changes made later to the values may invalidate the comment description altogether.

So what’s the answer?... Create an Enum:

enum DeviceStatus {
    Disabled = 1,
    Enabled = 2,
    Hybrid = 3
}

Then we can do this:

device.setStatus(DeviceStatus.Enabled);

The code has been improved by creating an Enum type DeviceStatus. It has three possible values that can be extended easily. Each value in the Enum has an underlying integer value. Thus in programming languages similar to C# they can be easily used in places instead hard-coding integer values.

The intent of the code is more clear and reduces the need for comments.

Comments

When I first started programming many years ago, I fell foul of over-commenting my code. It's a trap all new developers fall into:

// declare integer variable
int count = 0; // initialize to zero;

// declare string
string name;

There is a natural tendency to do this when you're new because you are learning. Commenting like this is akin to note-taking. It might be useful short term but in the long term it just adds unnecessary noise.

I prefer to comment only in a few instances.

Examples include:

code logic that is unable to explain itself adequately.
interfaces - using a <summary> boilerplate on interface methods.

// Customer's FTP server has intermittent network connection issues. 
// Retry a few times before giving up.

bool success = false;
int failCount = 0;

while(!success)
{
  success = await _ftp.Upload(file);

  if(success) break;

  failCount++;

  if(failCount > 3) break;

  Thread.Sleep(2000);
}

If you aren't confused by what a piece of code is doing, but rather why it's doing it at that moment, then a comment should be added. In the example above, the code is telling us a file is being uploaded over FTP - but it may not be obvious why the while loop is being used.

The comment is valuable here is it explains the reasoning as to why the logic has been implemented in this way.

Thank you to all who have followed and liked my posts - I will be back with more soon! 🤓

Clean Code – Part 1

Dalbir Singh — Mon, 24 Aug 2020 00:25:55 +0000

Clean code is akin to keeping your home/workspace tidy. Cleaning requires effort, whereas leaving garbage doesn’t.

While I’d love to mention some examples of poor code I’ve seen over the years, I too have fallen foul in the past.

Clean code isn't about vanity! Large messy un-refactored code only adds to technical debt. When another developer works with the same code you’ll have to double the time for them to complete the task due to messy code. Bear in mind time and effort can quickly grow exponentially as each developer hacks and contributes to the same messy code.

Below are suggestions to help keep our code clean.

Move hard-coded values to the database

Instead of this…

do this...

It’s very easy to write constants such as tax rates and bool switches directly into your code without thinking about the long term repercussions. I’m referring to changing values.

In cases like these it is far better to move these values into a database table, or at the very least the application configuration file. This way it will be much quicker and safer to make changes as opposed to opening up the code many years later and making changes, compiling and then praying its works while you upload… you get the idea.

Guard Clauses

Guard clauses follow the fail-fast principle. In the example above I’m performing a null check on the injected IEmailService reference supplied to the constructor (assume I’m using DI). If the reference is null, a related exception will be thrown during runtime.

Dealing with null references is an act of life for any developer. Using guard clauses throughout your code promotes error checking and is a good habit to develop.

Eagle eyed developers may have noticed I’ve compacted an IF statement to one line. You don’t have to do this, but I find it creates less noise and is more succinct.

Choosing appropriate class names

Poor class names…

Class names typically work best when they are nouns. However in more complex scenarios as shown above it is easy to fall foul of this when you need to describe two related classes.

Here’s one solution to fix this:

This is much cleaner and concise. I’ve used inheritance by creating a base class of Customer and then deriving two subclasses from it. In this instance, it allows for shorter class names since there is some context through the inheritance.

As a final note, I’m not a fan of using inheritance-based models everywhere throughout a solution unless there is a valid case as illustrated above. It can add to unnecessary complexity.

Thanks for reading! 🙂

Part 2 is available here:

Article No Longer Available

C# - Handy Features

Dalbir Singh — Fri, 21 Aug 2020 21:28:43 +0000

C# has been improved greatly over the years with useful features that have increased productivity for developers.

Below I’ll explain a few of my favorite features.

String Interpolation

In many programming languages, writing a string with embedded variables can be cumbersome. The longer the string, the more noise is added affecting readability like so:

C# 6.0 introduced a new string interpolation feature in which the variables can be written as expressions without the need for awkward string concatenation:

This results in the same output, but the code is much easier to read and maintain. To use this feature the string must begin with the $ symbol . String formatters may also be applied as shown in the Score variable.

As a plus – expressions will be highlighted within the whole string for better visibility in Visual Studio.

Expression-bodied function members

If you’ve created a few C# POCO classes over the years, I’m willing to bet many of the properties you’ve written are single read only statements.

Here’s a typical example where FullName is a read only property:

...And now here’s the same example using the FullName property as an expression-bodied function member:

The output is identical to the previous example. The code has been compacted down to one line, reducing noise.

Null-conditional operators

Null checking is an important subject for producing stable apps. Until now, null checking has often been verbose. Here’s a typical null checking statement combined with a ternary operator:

With C# 6.0 null checking becomes more succinct:

In this example the variable firstName is assigned null if the person object is null. If the person object is not null, the value of the FirstName property will be applied. This works thanks to the ? operator.

But what if we want to supply a substituted value for null values, similar to the ternary operator approach?

This can be solved by using the null coalescing operator:

Here, the expression always returns a string. The rules of the ? operator ensure that the left-hand side of the operator is evaluated only once.

Happy Coding 🤓

Build a Web Console with ASP.NET and SignalR

Dalbir Singh — Sun, 16 Feb 2020 14:06:11 +0000

What is it?

Web consoles are often featured on AWS and Azure. They offer meaningful feedback via output messages while executing time-consuming tasks.

I had to build something similar for a client recently and did some prototyping using ASP.NET with SignalR.

There are many articles on the web describing how SignalR works - and some useful examples that involve creating a chat server/client. Rather than getting bogged down in the details, I think it would be helpful to see SignalR in action.

I've uploaded my 'web console' prototype project to Github, which is a simpler implementation of SignalR with ASP.NET.

If you work with ASP.NET and are curious about web consoles feel free to download and have a play.

Documentation can be found within the Readme on GitHub. 😉

dalbir-singh / signalr-web-console

A web based output console for displaying progress messages when executing tasks using ASP.NET C# and SignalR

signalr-web-console

A web based output console for displaying progress messages when executing tasks using ASP.NET C# and SignalR.

What is it?

This repository contains a simple ASP.NET web application using SignalR to send status/progress messages to the client.

This feature is useful when a user triggers one or more time consuming backend processes, usually between 10-30 seconds.

In addition to just displaying messages, the project includes a console for printing the messages a.k.a web console.

Do note, the console is read-only - for printing messages.

How to run

Clone the repo, restore nuget packages (clean & build) and run!

(ASP.NET - 4.7.2 .Net Framework)

How does it work?

When you launch the project, a page will load with a button and a console window.

When you click on the button, an AJAX request will be posted to the server and time consuming tasks will be simulated. As each task completes…

View on GitHub

Building and Testing Webhooks with RequestBin

Dalbir Singh — Sat, 01 Feb 2020 16:22:23 +0000

I'd like to share with you all an invaluable online tool I've used over the years for Webhook integrations. It's called RequestBin.

In this article I will discuss:

How Webhooks work (short primer)
A typical Webhook example (using Paypal)
Webhook Development using RequestBin

How Webhooks work

In most cases, when your application interacts with a third-party API it behaves as the client making the request and receiving responses. However, in some cases a third-party service may wish to post some data directly to your application at any time.

To facilitate this, you'll need to setup an endpoint within your application which can accept a GET/POST HTTP request. This is known as a webhook, and once it is setup you'll need to provide the full webhook url to the third-party service so they know where to send the HTTP request to.

Many third-party API services utilize Webhooks from Messaging to Payment Gateways.

A typical Webhook Scenario: Paypal IPN Webhook

I'm going to walk you through a typical webhook scenario using Paypal integration.

Imagine in your web application you have built a shopping cart which uses PayPal for processing payments. Assume you have setup a Webhook (endpoint) within your application that will accept and handle a HTTP POST request...

The customer creates an order and clicks on the checkout button. They are redirected to Paypal to make payment.

The customer authorizes the payment by clicking on the 'Pay' button on the Paypal website. Paypal does two things;

Generate a IPN (HTTP POST request) to your webhook with payment status information eg.('OK', 'DECLINED'),

Redirect the customer back to your web application.

When the customer is redirected back to your web application they can expect to see the result of their payment/order (Whether it was accepted).

IPN - Instant Purchase Notification

Paypal has a webhook feature called IPN; Instant Purchase Notification. Put simply, after a customer makes a payment it will generate a HTTP POST request to your web application (your webhook endpoint). The body of the HTTP POST request will contain information on the payment status of that order.

Paypal configuration setting for IPN. The 'Notification URL' refers to the webhook endpoint in your web application; the IPN HTTP POST will be sent to this url.

When your webhook receives an IPN HTTP POST request, it's up to your application/back-end on what to do next with this information. Paypal IPN only has one task; to send a HTTP POST to your webhook containing payment information. Typically, once your webhook receives the IPN request you would update the order in your database with the payment status result.

Webhook Development using RequestBin

Let's use another scenario...

Scenario: You have received a new requirement to integrate a third-party internet service eg.(Payment Gateway) into your business web application.

As you read the third-party integration guides you soon discover that you'll need to build a webhook endpoint that can accept HTTP POST requests from the third-party to your web application.

The third party has simulation tools you can use to trigger a HTTP POST request to your webhook endpoint for testing purposes.

One of the tricky aspects of building and testing webhooks is due to network connectivity eg.(Firewalls). Initially, you will build, experiment and test the webhook locally on your dev machine but that represents a problem.

How could the webhook running on your dev machine 'receive' the HTTP POST from the third-party?

...or put another way, how could the HTTP POST request from the third-party reach your dev machine over the internet?

Depending on your environment you have a few options:

If you're working from home you could enable port forwarding on your router to redirect HTTP/HTTPS traffic to your local dev machine.
If you're working in the office, your dev machine will be much more isolated from incoming connections via the internet. Also, while special traffic policies could be put in place to allow incoming traffic for local dev machine good luck getting the sysadmin to agree to that! 🤭

dev: so if you could just setup a custom traffic policy allow incoming HTTP/HTTPs connections to reach the webhook on my dev machine, that would be great! 🙂

sysadmin:

Neither option is desirable from a network security standpoint, especially long term.

If only there was a way you could create a disposable container on the internet that collects every type of HTTP request (GET/POST/PUT) sent to it. This container could have a unique url which you can then supply to third-party services for webhook development.

It would essentially be a bin of requests... 😉

RequestBin.com does exactly this!

I'll show you how to setup a bin, simulate sending HTTP requests to the bin and finally inspecting the requests.

Creating a bin

Go to RequestBin.com and click on the blue button 'Create Request Bin' (uncheck 'Private').
A disposable bin will be generated with a unique endpoint url. You'll send HTTP requests to this url and see them arrive instantly:

Sending a HTTP request

You can use any HTTP client such as Postman to send a HTTP request to the bin.
I'll be using a HTTP Request simulator provided by ReqBin.com
You'll need to paste the endpoint url of the bin. In my case I am posting JSON so I have set the content type to application/json and added a payload with order payment information (you can add whatever valid JSON you like).
When you're ready hit the send button and watch the bin very closely - you should see the request immediately appear:

There it is... pretty neat! - With this approach, there are no messy firewall issues to contend with, it just works. You can drill down to greater details of every HTTP request such as headers.

There is no substitute for testing a webhook against your actual web application, but using RequestBin can make the development much easier. You could copy the requests you receive in the bin into the Postman app and then initiate a HTTP request to the webhook hosted on your local machine for a close test.

Finally, there are some other tangible benefits using these types of bins:

Investigation, R&D - Integrating third-party services takes an enormous amount of time and resources. Because of this developers and stakeholders will be keen to test/play with sandbox integrations before fully committing to doing the work. Bins like RequestBin.com enable one to quickly interact with third-party webhooks without having to write any code or setup/configure networking infrastructure.
Troubleshooting - With any type of third-party integration they'll always be some technical hiccups randomly occurring. With RequestBin you have another webhook endpoint completely unrelated to your servers and their network. This can be very useful for debugging issues. For example, suppose you have discovered that there have been no requests coming into your webhooks on the production server for the last several days. Who's to blame - the production server or the third party?... A request bin will reveal!

I'll leave you with a list of recommended request bins, best of luck with your webhook integrations 👍

Bins/Tools

https://requestbin.com/
https://requestbin.net/
https://reqbin.com/ (Used for generating HTTP requests)

Is XML Dead?

Dalbir Singh — Wed, 29 Jan 2020 22:21:49 +0000

Today I was asked to provide technical consultation for a customer involving the generation of an XML document.

These days we developers play with JSON, but it is worth noting XML played some influence with JSON’s global adoption. You’ll often hear a lot talk about data models, sequences, markup and so forth in the JSON community – lessons that were learned from putting together XML standards.

<?xml version="1.0"?>
<catalog>
   <book id="bk101">
      <author>Gambardella, Matthew</author>
      <title>XML Developer's Guide</title>
      <genre>Computer</genre>
   </book>
   <book id="bk102">
      <author>Ralls, Kim</author>
      <title>Midnight Rain</title>
      <genre>Fantasy</genre>
      <price>5.95</price>
   </book>
</catalog>

It’s been a while since I authored an XML document – I was reminded how the data structures are easier to read and understand. That’s not to say JSON isn’t readable, its just that with XML and it’s SGML derivatives the model is easier to comprehend, initially at least.

When I started thinking about how to parse XML documents again, It was then I was reminded why JSON is loved. While XML presents the data in an immediately readable format, JSON presents the data in an easily digestible format for your application code. No need, for complex XPath queries, just bind it to your internal model and your done!

If JSON is the preferred choice for data transfer within applications, does XML have anything left to offer?

Yes – documents…

XSLT

XSLT (eXtensible Stylesheet Language Transformations) is a language for transforming XML documents into other XML documents, or other formats such as HTML for web pages, plain text or XSL Formatting Objects, which may subsequently be converted to other formats, such as PDF, PostScript and PNG.

Example of XML/XSLT: In the image above you can see an example of XML and XSLT working together. The XSLT file uses XPath queries to lift information out of the XML document and render the content using templates. The output is shown below.

XML still works best for documents. Documents by their nature have a form of structure that is represented better through XML.

Combine XML with XSLT and you’re able to perform impressive transformations with nothing more than .xml and .xsl files.

So, Is XML Dead?

Not yet – XML still has its place for document-based structures. Also many financial institutions rely heavily on XML based formats for transferring information between enterprise systems that were built in the 2000s.

It’s well known financial enterprises such as Banks are reluctant to ‘upgrade’ their systems unless they really need to. So XML may not be the new kid on the block, and relegated to more mundane infrastructure but it’s still alive and kicking. 🤓

What about you? - Do you still use XML day to day?

SMSS -'Connect to Server' Hell

Dalbir Singh — Tue, 28 Jan 2020 23:01:57 +0000

If you've used Microsoft SQL Management Studio long enough you've probably encountered the connection dialog box from hell.

Connection settings randomly disappearing

No matter which version of SMSS you use, there's an inconsistent behaviour with it remembering SQL Server connections - applies to all editions.

Sometimes, your last used database server connection settings will be remembered and at other times SMSS will completely forget them. If you're using SMSS on a daily basis and accessing different server instances it can cause much frustration.

The fix - 'Registered Servers'

Various solutions exist to resolve this, some with mixed results. One of them involves tweaking the entries via the registry - no thanks! 🙄

The other, is much simpler using SMSS's Registered Servers feature:

First, fire up SMSS - bypass the 'connect to server' dialog box, you won't need to be connected to a database instance for this.
Then navigate to View -> Registered Servers.
Right click on the 'Local Server Group' folder and select 'New Server Registration'.

Enter the SQL Server instance connection details:

You can repeat this process and add as many SQL Database connections as you like here.

Once all your connections have been entered into the 'Registered Servers' feature, the connections will be available in the SMSS 'Connect to server' dialog.

and that's it - no more missing connection settings 😎