Tuesday, December 4, 2018

New Page With External Blog Posts

Some folks have requested links to the blog work I've done for clients. I added a new page with some of my work. I'll update it maybe each quarter. In lieu of that, I'm thinking about cross-posting the work I do here as well so look for that in the near future. In the meantime, check out the posts I've added to the new page!

https://blog.thedailylessonlearned.com/p/blog-page.html



Wednesday, November 28, 2018

OOP Concepts: The Aggregate Class

One fundamental principle in object-oriented programming (OOP) is hiding data. The idea is that you use a class to encapsulate data associated with some entity in the business model. All data access and manipulation should be performed by methods on the class.

This principle also applies to collections. In this post, I'll cover some details of a specific pattern for hiding collections. This pattern is called the aggregate class. An Aggregate Class follows the same principles as any other class: data hiding, separation of concerns, etc. It also has the same benefits: reuse, contained changes, centralized business logic.

The Problem With Functional Style in OO Languages


With so many developers using ORM's and Linq (and other lambda-based operations in other languages besides C#), we see a trend toward functional style programming in OO languages such as C# and Java. We should still be careful to protect the data since OO languages do not work the same way as functional programming languages.

In OO languages, collections such as lists and arrays still allow you to change the state of each element. Even if the collection itself is read-only, it's only a pointer to the underlying objects. You could, perhaps, use structs in C#. But then again, you might not have control, and still, you'd have to go the extra mile to properly handle state changes.

If you're really doing functional programming, you won't mutate the state of a record. Some OO concepts have bled into functional languages like Lisp and F#. Basically, the lines have blurred on both sides. When it comes to OO languages, classes are mutable by default. The whole point is to mutate state within a class instance! So, we need to be careful to protect the state of collections from corruption by external manipulation.

Enter the Aggregate

The Aggregate Class is just the thing to keep our data within collections protected. The aggregate class helps by containing changes to the collection. Also, it gives us a centralized place to organize our collection logic. That's really important too!

As an example, let's consider an application for managing people within a school system. There are several types of people in a school. Major classifications are students, teachers, staff, and administrators. There may be some database table containing basic information of all persons: name, phone number, etc. But, indeed, there will be various information for each type of person. 

Specifically, a teacher may be tenured. Say a teacher earns tenure after five years. You can write a filter using Linq to get all tenured teachers like this:


var tenuredTeachers = persons.Where(
    person => person.Role == "Teacher" && 
    (DateTime.Now - person.StartDate).Days > (365 * 5)
);

As you can see, it can be a little messy. And of course, this encourages copy-paste coding because you might need the logic elsewhere. How do we fix this?

First of all, we'll make a Teacher class and put an IsTenured property on that to contain the logic.

var tenuredTeachers = persons.Where(
    person => person is Teacher && person.IsTenured
);

Already looking cleaner!

Next, let's do away with the "person is Teacher" by using OfType<Teacher>:

var tenuredTeachers = persons.OfType<Teacher>().Where(
    person => person.IsTenured
);

Even better! OfType will filter the collection down to the specified sub-type. But must we repeat this code every time we need teachers? No! We can use the Aggregate Class. Let's make one like this:

class Persons
{
   public IEnumerable<Teacher> Teachers { get { return _persons.OfType<Teacher>(); } }
}

And we can use that to get teachers wherever we need them. But we can go a bit further and create a Teachers Aggregate Class too.

class Persons
{
   public Teachers Teachers { get { return Teachers.Get(_persons); } }
}

class Teachers
{
    // factory method
    public static Teachers Get(IEnumerable<Person> persons)
    {
        return new Teachers(persons.OfType<Teacher>());
    }

    private Teachers(IEnumerable<Teacher> teachers)
    {
        _teachers = teachers;
    }

    public Teachers TenuredTeachers { get { return _teachers.Where(t => t.IsTenured); } }
}

And with that, we can return only the tenured teachers and contain the logic. Now in our business objects, controllers, or wherever we need to get tenured teachers, we can use this Teachers Aggregate.

var tenuredTeachers = persons.Teachers.TenuredTeachers;

And there we have some nice clean code!

Applying Functions to Aggregates

We want to protect the data within the collections. There's a pattern we can use to pass functions to the collections within the Aggregate Class. It's basically the visitor pattern, and it goes a little like this:

persons.Teachers.Apply(t => notification.Notify(t) );

// or

persons.Teachers.Apply( notification.Notify );

In this case, we're passing the "Notify" function to the Teachers Aggregate. The Teachers Aggregate will handle passing it along to all the teachers.

Even with the Apply function, we aren't really protecting the data unless the Teacher class protects its own data. A typical pattern you'll see is that the Teacher or Person class is a POCO—meaning it just has public properties. POCOs are really just DTOs. They're intended for transferring data, but you shouldn't really manipulate the data everywhere in your code. This is where you have a real divergence between the intention of OO and how we often see the languages used in practice.

On the flip-side, we see functional programming operating on records. But when that happens, the default is to create new records as a result of the application of a function. A Map method in a Teachers class would look like this:


public IEnumerable<Teacher> Map( Func<Teacher, Teacher> map )
{
    return _teachers.Select( t => map( t.Clone() ) );
}

In this Map method, the elements of the internal collection are copied then passed to the map delegate given to Map. Surely, this is an odd mix of OO concepts and functional principles. The Aggregate Class shouldn't really return a collection of the internal data even if it's a copy. This is really a generic type of method that has use in low levels of your application stack. It isn't beneficial. Think about it this way...what business function does "Map" perform? None. Which brings us to putting business methods in Aggregate Classes, which is the proper way to do things in the OO paradigm.

Business Methods in Aggregate Classes

What do you actually need to do with Teachers? We've already seen a case for "notify tenured teachers." We can expose other useful subsets of teachers like TeachersWithAbsences. But if you really feel the need to present a way to apply arbitrary filtering, the items in the set should prevent modification of internal data AND the set should prevent altering the items in the set. You can run into trouble with filters if they allow the collection the change:


// Dangerous Notify method...
public async IEnumerable<NotifyResult> NotifyAync( Func<Teachers, Teachers> filter )
{
    foreach( teacher in filter( _teachers ) )
        yield await teacher.NotifyAsync( notification );
}

// Dangerous call to Dangerous Notify method...

... await teachers.NotifyAsync( teachers => teachers.Where(t => t.IsTenured ? t : null ) );

Here, the programmer is returning null when a teacher isn't tenured. The implementation of NotifyAsync, while intended to be as flexible as possible, invites danger. A better implementation prevents modification to the internal collection as follows:

// Better Notify method...
public async IEnumerable<NotifyResult> NotifyAync( Func<Teacher, bool> filter )
{
    foreach( teacher in _teachers.Where(filter) )
        yield await teacher.NotifyAsync( notification );
}

// Dangerous call to Better Notify method...

... await teachers.NotifyAsync( teacher => 
  { 
    teacher.Email = null;
    return teacher.IsTenured; 
  } );

Here, the collection can't be changed, so it's better. But still, unless the underlying items are adequately protected, they can even be modified in ways that are dangerous. This example is a bit obvious, but similar trouble can occur when the underlying data is allowed to be manipulated when it should not.

We can go all the way to protect the underlying data by either denying access to the underlying items altogether or by limiting exposure to the underlying items.

// Best Notify method...
public async IEnumerable<NotifyTeacherResult> NotifyAync( NotifyTeachersFilter filter )
{
    foreach( teacher in filter.GetFiltered(_teachers) )
        yield await teacher.NotifyAsync( notification );
}

public class NotifyTeachersFilter
{
    public bool? IsTenured { set; private get; }

    internal IEnumerable<Teacher> GetFiltered( IEnumerable<Teacher> teachers )
    {
        return teachers.Where(t => IsTenured != null && t.IsTenured == this.IsTenured);
    }
}

With the filter type, we've entirely walled off access to the underlying items in the collection. This is a simple example of how to use filter types with an Aggregate Class. You can go further by passing a collection of filters or even an ordered collection.

Final Thoughts

I want to conclude by saying that using Linq is not precisely the same as Functional Programming. Sure, you can and should bring some of the concepts of FP into an OO language. But, remember that the language itself is built for OO programming. The principles won't translate 100%, and you can end up shooting yourself in the foot quickly by trying to do FP in an OO language. It's better to switch to a functional language like F# so you get the full support and benefits. When using FP concepts in OO languages, keep in mind the OO principles and use the Functional Programming practices with a grain of salt. Keep in mind that they can help but use with caution!



Friday, October 26, 2018

Taming Events: How to Use SoC to Organize Events.

If you're using any kind of eventing system in JavaScript, whether the built-in events or something more, you'll want to give some thought to how you organize the events. In the grain of self-documenting code, SoC, and containing risk I offer some suggestions on how to pull it off without pain.

What's an Eventing System?

Basically, an eventing system is a way to raise an event in one context (such as in a function or class) and listed for events in one or more different contexts. It's a great way to decouple your code, but you should be careful not to paint yourself into a corner. Here's an example of an event and a listener (you've no doubt seen this kind of thing before):

$input.on('change', handleInputChange);

This is an example of a JQuery listener. It listens to DOM events on an input that's represented by the variable `$input`. When the `change` event is raised by the DOM, the `handleInputChange` function is called in response. This is about as basic as it gets. Let's see how to raise an event programmatically.

$input.trigger('change');

This is the JQuery way to trigger an event. Any listeners such as `handleInputChange` will be called in order once the event loop comes around to them in turn.
Mozilla lists a boatload of native events on their developer site.
Some eventing systems, such as Backbone Radio (part of Marionette) or Redux, are built for handling custom events. You define the events, raise them in code, and listen to them. For example, Backbone Radio works a bit like this:

Backbone.Radio.channel('my-channel').once('my-event', handleMyEvent);

// elsewhere

Backbone.Radio.channel('my-channel').trigger('my-event', ..args);

And this will work just fine functionally. The event will trigger and the handler will handle it. You'll add more channels and more events. One day, you or a future developer will need to find out what channels are out there. One problem is, you can accidentally duplicate channels and events. Who knows what's listening to all those events. Organization to the rescue!

Organizing Events

In an event-driven system, you've got to be organized or you're system will essentially be running wild. By "organized", I mean three things:

  1. Use well-defined conventions. 
  2. Keep things in logical places. 
  3. Know where and how to find something easily.

Failure to organize will result in great difficulty resolving issues. For example, you might need to hunt and peck your way around the code to find what events are raised in the first place. Or, you may need to run the application in order to figure it out. Worse you might not be able to run the application in its current state. There are ways to solve these problems!

Make Channels/Queues Explicit

You can put all of the channels into one file. Then, simple require or include this file wherever you need to interact with events (trigger or listen to). This advice isn't just for Backbone Radio or even JS frameworks, it's true for any given event-driven system. If you're using a message queue via ruby or python, to name a few, you still want to separate where your queues are connected from where you're using them!

Here's an example using C# for sending messages to a queue:


// somewhere in a method 
 this._messageQueues.UserMessageQueue.QueueEvent('user-update', eventData);

OK, I admit that example is a bit generic. But, you can see how easy it is to raise an event with this system of organization.An instance of the class that holds the message queues is injected into the class through the constructor (not shown). Then the instance is used to get the specific message queue which is used to queue the event. This beats the alternative:

// in the same method
  SomeSpecificMessageQueueClient queue = new SomeSpecificMessageQueueClient('user');
  queue.Initialize();
  var topic = queue.GetTopic('user-update');
  topic.SetConfiguration(...)...more boilerplate code...
  
  ...finally, 30 lines of config code later...

  topic.QueueMessage(messageToQueue);

Alright, I concede once again to making this more complicated than necessary. We could have something like Queues.get('user') right? Of course we could! That's less boilerplate which is good. However, the problem still exists that all queues are adhoc in a string. Better to be explicit so that you have self-documenting code!
I still don't really like the fact that we're defining the event keys as strings. I'd like to be more explicit about that too so we know which events are raised throughout our code. In large code-bases this gets to be really important. Smaller code-bases can benefit too. We can make the events explicit too.

Make Events Explicit

By making the events explicit, we can easily see what events are raised and listened to in a system. We might be raising events for no reason, for example. When they're explicit, as in a method or function rather than a string, we can see how they're being listened to. Remember the `once` listener in one of the early examples? That registers the listener to listen one time to the event, then deregisters it after that first time. In this case, we would have an explicit method for the event such as `MyChannel.listenToMyEventOnce(listener)` and no methods on `MyChannel` named `listenToMyEvent`. From the class itself, we can easily see that there are no perpetual listeners to `MyEvent`. Whereas, if we have `once('my-event')` scattered throughout the codebase, we would have to search everywhere to find out. That's a long process. Besides, you might not have all the consumers of your events in the whole codebase when you're using something like a message queue. In fact, that's the whole benefit of message queues in the first place! Here's a more comprehensive code sample of what I'm advising here:

class UserEvents {
  private const BEFORE_SAVE = 'user-before-save';
  private _queue;

  constructor(Queue){
    super();
    this._queue = new Queue('user');
  }

  raiseBeforeSave(user) {
     this._queue.raise(BEFORE_SAVE, user);
  }
  listenToBeforeSave(callback) {
     this._queue.on(BEFORE_SAVE, callback);
  }
}

In this class (which is sort of Typemock-ish), I've defined all of the user events for now. The queue type is injected into the class so it can be swapped out for testing (or even adapted to use a different queue system). The consumers of UserEvents has no idea how it implements or even interacts with the queue. We've got all that detail contained within the domain-specific class "UserEvents".

Finally...

I just want to leave you with a final thought...this is all about self-documentation. It makes for easier programming and issue resolution without having to strap on a debugger or hunt through mounds of code. One addional benefit to containing all the eventing logic...you can see how easy it would be to add logging to the Queue right? Just pass in an instance of your custom LoggingQueue class that has the same methods but which logs each event. "raise" would first call the logger, it can easily log the handlers attached. And now you have a nice way to see the chain of asyncronous events that are always so much trouble to understand in an event-driven system! Happy Coding!

Monday, July 16, 2018

C# Logging: Where To Setup The Logger

Applications need logging. In C#, you will typically log various types of events like exceptions, debug, and informational. Your logs will contain valuable information which you'll use to tune your application and understand user behavior.

It's easiest to either pass an enum value to a single Log method or call a specific method to write different types of events. It's typical to write to different logs depending on the context. The problem is, where and how do we access the logging API from our methods?

Dependency Injection


Dependency Injection is one possible approach. If you go this route, you have to pass around a logger to all your classes as a dependency. You can use constructor injection and take the logger in as a constructor parameter. For a User class, you would pass it in along with the UserRepository as follows:


public class User
{
  private readonly IRepository<UserData> _userRepo;
  private readonly ILogger _logger;

  public User(IRepository<UserData> userRepo, ILogger logger)
  {
    _userRepo = userRepo;
    _logger = logger;
  }
}


The User class takes in the logger along with any other dependencies.

Via IoC Container

Even if you use an IoC container like Ninject or Unity, you have to add the logging interface to all the constructors and make a class member. With the IoC container approach, you can also ask the container for the implementation.

Container.Get<ILogger>()?.LogError(...);

Results and specific approach may vary according to the container, but this will at least allow you to fetch the logger whenever you need it without having to pass it around.

The .NET Core Way

In .NET Core 2.1, there are two ways to go about it as written by Luke Latham. Luke recommends using the LoggerMessage class over the LoggerExtensions for high-performance applications.

The Problem With DI

But let's suppose that you're not using core and you don't like the idea of adding the logger dependency EVERYWHERE! It isn't a dependency of the class that has anything to do with the business logic of the class. It's an implied dependency of all classes in the application. If you first design the class without the logging dependency, then you have to add it when you need to use logging.

IoC containers make this easier, but what if you have static methods from which you need to log (it happens)? In that case, you don't have constructor variables. You could pass the logger in the method params, but then you're passing around a logger. That's not a particularly elegant pattern! For one thing, you end up with more parameters. Another, you get into the habit of passing things around you may or may not need.

As Global

If it's a dependency everywhere, it's a global dependency. I don't like globals for many things. They are for configuration and that's really about it. It's beneficial to have a global logger too!

I also don't recommend statics for most things. Well, the logger could be a static global so long as it doesn't have mutable state. In other words, so long as you set the logging configuration once and leave it along throughout the entire application lifetime.

Log.LogError(...);

And in your implementation of the static method, you can get it from the container or some other global context.


public static void LogError(params object[] logParams)
{
  Container.Get<ILogger>()?.LogError(logParams);
}

This is actually a better practice since you only have to change your Log class if you change IoC containers and the interface doesn't match. It's better separation of concerns (SOC). The place to change the logging is in the Log class rather than everywhere else!

Concluding


Most of the methods discussed here are fine and dandy. I'm just not a huge of fan of having to pass things around in every class. I wouldn't extend this idea to something like a repository though, those are business logic specific dependencies that actually have meaning to the class at hand. A User class taking a UserRepository is meaningful. Every class taking an ILogger has no meaning and actually distracts from the purpose of the classes.

In sum, global is the place for the logger!

Book Review: Astrophysics for People in a Hurry

While I was shopping for a new Chromebook, Amazon recommended some books for me. One of those books was Neil deGrasse Tyson's "Astrophysics for People in a Hurry" (if you're interested, please use this affiliate link or the one at the end to purchase your copy - I'll get a bit of commission at no extra cost to you). My wife got me this book as a gift in 2017 as a matter of fact. I have to say, it was a fun read!


I've read a lot of pop-physics books over the years. I had already been exposed to most of what is in this book. Still, it was a fun read! Neil just has an entertaining personality and it shines through in the book as much as it does over audio or on TV.

Contents

Just to give you an idea of what's in this book, some of my favorite topics are:

  • Dark Matter
  • Dark Energy
  • Invisible Light


Neil starts the book at the beginning. THAT beginning. The Big-Bang. He also has a chapter called "On Being Round."

On Being Round


Well, it's not about being overweight so much as it is about being massive. As Neil says, any mass in space will experience surface tensions which force it into a round shape. Spinning objects will have a more-or-less flattened round shape. Pepper that with anecdotes about spherical cereal boxes and a whole wealth of other information and you have a pretty good idea about one of my favorite chapters in the book!

Final Thoughts

I don't want to spoil anything else for you, but let's just say there are some pretty spooky things in this book! One of the latter chapters speaks of things that will leave you awestruck! And this is why we love Neil deGrasse Tyson, isn't it! He can give us the heebie-jeebies and leave us awestruck at the same time!

If you're into this kind of thing and you want a fun, easy read by one of the best minds in the physics world, read Astrophysics for People in a Hurry! That affiliate link will take you right to the order page on Amazon so you can order it now.


Sunday, July 15, 2018

Bought a Netbook

Last night I did some comparison shopping for a new netbook. I posted the details in this blog along with some affiliate links. I figured, since I'm going to buy a netbook anyway, I might as well share the experience.

A Software Developer's Rationale for Affiliating


I'm trying the Amazon Affiliates program for this experience. There's a benefit to both of us. If I'm doing some comparison shopping, we will gain maximum advantage through re-use if you (dear reader) were in the market for a netbook. And in return, you'd be helping me out by buying your netbook through one of my affiliate links. It costs the same for you, and I get a little commish for having posted my experience here.

What I really want is to share some good things with my readers. For example, I applied to be an affiliate for PluralSight. I love their selection of training videos, and I hope that happens because I believe in what they have to offer! But, I digress.

And the Winner Is...


Getting back to the topic. I went with the ASUS Chromebook C202SA-YS04 11.6" (that's the affiliate link in case you'd like to follow suit and get a great little netbook for yourself or a loved one). It seemed like the best deal on the market. With Prime Day coming very soon, you might want to keep an eye out for a good deal on it. It really came down to having the most/best reviews in the price and spec range.

Basic Specs

Here are the primary technical specs for this model.
  1. 4 GB RAM - I'd like more, but I don't know that I would need more.
  2. 11.6-inch anti-glare LED-Lit HD monitor - I'll be using this on the train a lot and sometimes that sun shines right into the windows. Anti-glare is a huge plus!
  3. 32 GB internal storage - I wanted the extra storage, wouldn't hurt whereas running out of space would!
  4. Chrome OS - I'm giving it a try. I use a lot of their apps and services, so why not. If I don't like it at all, I'm going to see about installing a Linux distro on it. Maybe Ubuntu. Ubuntu on a netbook...yeah!
  5. 2.65 pounds - this is the main thing. I needed something lightweight because I'll be slinging it on my back. I have a lot in my pack, and the laptop is just too much to lug around.
  6. Dual processor - A lot of the less expensive netbooks have a single core processor. That means only executing one thread at a time. I prefer to have my processor multi-task so that I can keep working while background processes run. I know it depends on the app and processor architecture, but 2 cores are usually better than 1.
So those are the basic specs. And that's part of why I went with this model.

Primary Deciding Factor

It really came down to the reviews. This one had the specs I liked, and it had the most reviews and a comparable rating to other netbooks in its class. To me, this says that enough people bought it and liked it enough to give a favorable rating. Statistically, a set of over a thousand reviews is more significant than a set of under one hundred. So I went with the popular vote.

I'll post some pics when I open it and do a quick review once I get a feel for Chrome OS. Thanks for hanging with me tonight! Have a happy Prime Day!

Saturday, July 14, 2018

Buying a Chromebook

Ok, so I have a Lenovo Notebook that I use for everything right now. It's decent enough to do what I do. I'm using it right now, in fact. I can use the internet. It works for programming. Sure, it isn't a top-of-the-line model, but it's getting the job done!



Except, when I take it with me on my daily bike or train ride and it's hanging out in my backpack adding 5 or 6 pounds to the load. Then it sucks! I need something lighter. I'm considering a Chromebook but I don't know which one. Maybe it doesn't matter since they're priced so low that it's not like it would be a total loss if it wasn't that great. But then again I don't want to be so annoyed that I can't be productive. I plan to blog a lot on it and need it to be portable.

Here are a few that I have in mind (I really am buying a netbook, but I want to mention that all the links are affiliate links, so if you would like to purchase any of them I get the benefit of a commision at no cost to you...and a big thank you if you do!):

ASUS

The ASUS Chromebook C202SA-YS02 11.6" has 4GB RAM, 11.6-inch monitor, and only weighs 2.2 lbs! I like the lightweight.

But then again, it's only got a 16 GB hard drive and the next level up has a 32 GB. The ASUS Chromebook C202SA-YS04 11.6" is the same but with the bigger hard drive. Apparently, 16 GB extra of hard drive adds 0.4 lbs.

The only thing is they come in dark blue. I'm not too concerned with color so long as it's not a standout color, but I would prefer something dark-grey or black.

Samsung

I could go with a Samsung Chromebook 3 XE500C13-K03US. It has a 4-GB RAM and a 32-GB Hard Drive. And, oh look! 2.54 lbs! And what else? A Dual-Core Intel. Hmm...Samsung, should I give you a shot or keep looking? There's only one left, but I am a sucker for familiar brands. I haven't had a Samsung laptop. I know other folks have had some problems with other types of Samsung products. 4 stars for this though. Let's see what else:

Acer

This Acer Chromebook 11 is looking mighty nice in Clamshell White. Not really my taste. I would get one for my daughter though. Ok, so it does come in black too.

HP

I do have experience with HP products - mixed but generally good on the hardware side. So there's the newest HP 11.6” HD IPS Touchscreen Chromebook. Touchscreen, eh? I never really worked with a touchscreen before. I might give it a shot! It's pretty lightweight at 2.5 lbs. Says the battery will last 12 hours on average! Most of the others were around 9, so that seems pretty good! 2 processor cores - another plus. The 16 GB hard drive is a bit of a drawback.

Decisions, Decisions...

In the end, I think I'll go with the masses. That second ASUS with the 32 GB has the most reviews and a four-star rating at the moment. Seems like it would be the best all-around. It's just a little more pricey than some of the others, but you get what you pay for right?