Friday, December 28, 2018

Happy New Year! And Forget Your Resolutions

This year has been full of fruit and frustration. With a new year just days away, I'm going to recap some things that happened this year and refocus some goals for next year.

Resolutions the Continuous Way


For the past two years, I've been doing resolutions a bit differently. I do them the Continuous Improvement way. A whole year to do one thing is a bit much, this is why they usually fail.

Instead, take it one month at a time and do smaller things. For example, I'd like to try CSA (Community Supported Agriculture) this year. I'll keep it in mind and make sure to take that on in some specific month. Other months will be dedicated to some other improvement. The key is to take on one key thing per month. In the past, I've worked on posture, starting grad school, and even kicking off this blog. I'll consider what accomplishments I'd like to make this year just after a quick recap of this year.

This Year In Review

There were ups and downs for this year. The biggest positive is starting graduate school in August. Swinging back the other way, the lowlight is when TagStation closed up shop and left the team of talented folks out of work...and just before the holidays. Between these two extremes, there's been a ton of growth!

I started blogging semi-professionally in May when HitSubscribe put out a call for authors. I've been busy as a beehive writing posts.

This year, I paid off the family car. That's a big deal for anyone who's experienced the joys of concluding monthly car payments!

I finally learned how to make good bread! I've made some baguette style bread and some fantastic whole-wheat loaves this year. The trick is to put a cast iron pan on the bottom rack of the oven and preheat that guy. When you put in your loaves, go ahead and put 1/2 cup water in the pan. Watch out though! It's going to steam up fast. DON'T GET BURNED! That steam causes the bread to form a really nice crust. I cut out the sugar too, I've been putting too much sugar in my breads in the past.

In global news, the stock market took a huge turn for the worst after peaking out. I won't get into politics on this one but it makes a lot of sense why this would happen if you understand a bit about economics.

In tech news, there's always a bunch of cover-fire on this topic. Reddit should have you covered to no end on this topic. I gave a talk this year on how we developers would do well to focus more on business concerns. Sure tech news has some impact on this, but not as much as knowing where the economy will head next year.

Next Year

Speaking of next year...2019 already? I have some goals lined up for next year.

I've already mentioned the CSA. And, my wife got me a home cheese-making kit for Christmas. 

That's a good excuse to try raw milk. In my state, it's now legal to purchase raw milk from a dairy. See, the cheese kit says the best results come from raw milk. I can make fresh Mozzarella or Ricotta. But the former will not work if I use ultra-pasteurized milk. The best results will come from raw milk.

Monthly Actionables


But, I won't be making some fell-resolution to do some grand thing next year. Instead, I'll break down what I really want to do into actionables for each month. January and February are all about career focus. If things go well in that domain, I'll be all set to work on some home improvement goals for later in the year.

Before that, I'm thinking March, April, and May for the CSA resolutions. I'll start this by buying into a month's share of food from a local CSA farm. If it works out, I'll go for broke the next month and buy-in for a year.

Late in the year, I'll be thinking about revisiting some past goals like practicing good posture. I do believe that things change so rapidly that it's going to be tough to call out any resolutions for later in the year. I've been meaning to improve my social media presence. If it fits in later in 2019, that's just one thing I'll get started on.

Lesson Learned

I know as well as you do that documenting and tracking progress is important for goalkeeping. Making the goals SMART is supposed to be a good way to make this happen. However, some things like "apply to grad school" are binary. So...the measurement is just true or false. I'd love to say I tracked my monthly resolves for this year, but I didn't. I was a bit loose with it. Still, I did a whole lot. Unfortunately, I only have my memory to serve these. Had I documented them I'd be able to account for the whole year. Maybe that'll be my new year's resolution...only kidding!

Perhaps that can be something for Jan or Feb.


Wednesday, December 12, 2018

And Now...A Lesson In Accounting: Indirect Method Computing Cash Flows From Operating Activities

A small departure from the usual technical topics. As many of you know, I'm studying business these days. The lesson of the day is about how accountants arrive at the cash flows from operating activities for the cash flow statement.
The statement of cash flows is useful in understanding how cash moves (flows) through a company. You use it to evaluate the company's ability to repay debts. That will determine how much investors and creditors they're willing to invest or lend the company.

Indirect Method For Operating  Cash Flows

If the first section of the statement of cash flows seems odd, the accountant is probably using the indirect method of computing cash flows from operations. See, it's difficult to compute cash flows from operations directly. Instead, they start with your net income and factor out changes in current operating assets and liabilities that are not cash.

For example, let's say your company has a current asset of $100,000 in accounts receivable. In that case, you don't have the $100,000 in cash — at least not yet — so you can't count that as cash inflows. Your accountant subtracts it from your net income to factor it out.

For other types of non-cash accounts that contribute to net income, the balance may be added or subtracted depending on the type of account. Depreciation expense is added to net income. And, any gains on the sale of assets are subtracted from (losses are added to) net income. After all these adjustments are made, the result is the net cash flows from operating activities.

Direct Method for Investing and Financing Cash Flows


After the cash flows from operating activities, you should see the cash flows from investing activities followed by the cash flows from financing activities. These are shown using the direct method. The records for changes in cash due to investing and financing activities are readily available.

The Bottom Line


Once you have an understanding of how the statement of cash flows works, you should find it useful in understanding how a business is receiving (inflows) and using (outflows) cash.


References:
Warren C., Reeve J. M. & Duchac J. (2016). Financial and managerial accounting (14th Ed.). Boston, MA: Cengage Learning.

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.