I don’t fully trust source control systems. Not even Git. That’s because I’m an old fella in the industry and I’ve been bitten too many times to fully trust systems.

Point in hand. I just had a merge from ‘develop’ royally screw up some code in such a way the effort to find and fix the change is greater than the effort to just blow away my working branch and pull again from remote.

Pro Tip!

When merging from another branch like ‘develop’ into your working branch, first commit and push your changes to remote.
That way, when your merge screws something up without you realising until after you’ve re-compiled and tested the merge – you do re-compile and test your merges right? – you can reset or blow away the branch (even delete your local branch and pull again if need be) without losing your hard-won changes.

Learning how code “hangs together” is crucial for all programmers. And it’s not that difficult.

Most software has an entry point, though it varies depending on the language or framework. Find and understand that entry point.

From there just follow the code. In procedural and object-oriented languages you’ll mainly be dealing with IF statements, SWITCH statements, calls to functions and calls to objects with properties and methods.

Watch what is called. Look at the parameters being passed into methods or class constructors.

Look at how variables are manipulated. Consider the scopes of variables and class properties – are the private to a function or class, or are the public? Are function parameters passed by value or by reference?

And think about namespaces – from the variables and functions that sit in the global namespace through to those nested under specific namespaces.

Functions will sometimes seem to be in a global namespace but are actually implicitly at a deeper namespace level thanks to using or include statements in the file (e.g. in C# and VB.NET).

PRO TIP: Make Find All (usually Ctrl+F) your best friend. If you come across a function or variable and don’t know where it’s defined or what it’s used for, any decent IDE with allow you to perform a “Find All” and list out all occurrences of it. Use that to trace the use of the variable/function.

But the most important thing you can do as a programmer is: take the time to read and understand the code. The more years of experience you have the easier and more intuitive it becomes, but always it is important. Learn how to follow the flows, intuit the structure and find where functionality lives.

This is the true heart of most programming activity.

I’m a very practical developer. My learning style has always been to learn how to do something, usually by example, now what it’s called.

As such, I know that I know how to write code with predicates, but I might still fail a multiple-choice test to describe what a predicate is.

So I looked it up again. And it’s really quite simple:

A predicate is a statement (or function) that returns either true or false.

You pass some data into the predicate. The predicate logic then performs a check on the data. Then the function/statement return a true or false result to the caller.

The 2 clearest resources with descriptions and examples I’ve found so far are this StackOverflow answer and this other StackOverflow answer (which is C# oriented).

A common example is a function or short comparison statement you write and pass into a function on a list that then performs a mapping or reduction on the list (e.g. to find a subset of items in the list that contain the value(s) your predicate function or statement is checking for).

For example, if I have a list or array of People objects and each object has an Age property, I can write a predicate …

(Person p) => (p.Age >= 18)

… that I pass into a select() function on the list to return only those people who are age 18 or older.

For example:

var australianDrinkingAgePeople = fullList.Select(Person p => p.Age >= 18);

In this case, it’s a shortcut for writing your own big for loops and if statements over the list (although there’s nothing to say that the select() statement doesn’t implement that logic behind the scenes).

From years of experience and use (and a few recommendations from other people), I recommend the following tools:

IDEs/Editors

• Visual Studio Code – Windows/Linux/Mac. It might be from
• Atom – Windows/Linux/Max
• Cloud9 – Browser-based IDE. The original version was better. Now owned by Amazon AWS and they’ve made a royal mess of the licensing, usage and documentation. Still good under the covers though.

GUI Git Managers

Command-line has its place but for the complicities of Git-based source control (and being a visual person), I prefer a good GUI for Git management.

• Sourcetree – Windows/Mac
• GitHub Desktop – Windows/Mac
• Git GUI clients list for all platforms.

File Compare and Merge

• DiffCompare
• BeyondCompare
• WinMerge

Web Proxy for Debugging

• Telerik Fiddler – Windows (Beta for Max/Linux)
• Charles Proxy – Windows/Mac/Linux
• OWASP ZAP – Windows/Max/Linux (I’ve not used this, but OWASP does good work in security and have seen others recommend it)

General Development Helpers

• JSON formatter – Great for inspecting large sets of JSON (and now XML and YAML)
• RegEx Testers (enter a regex expression, test it, find out what it does):
  • regex101.com
  • regexr.com
• Can I Use – The best resource to determine what CSS and JavaScript feature the major browsers support.

The &$ prefix of an argument name passed into a PHP function means the argument is passed “by reference” (as opposed to “by value).

For example:

function publish_contributor_post($arg1, &$arg2)
{
   ... 
}

In this example arg2 is passed “by reference”.

See also: https://stackoverflow.com/questions/20419613/php-string-what-does-this-mean

During an investigation of date related issues in a project I’ve been working on in the day job, I’ve created a detailed write-up on working with dates in JavaScript based on experience.

---

Things to remember about JavaScript Dates:

• JSON.stringify() in JavaScript will serialize a date to UTC.
• Month numbers start at 0 (zero) in JavaScript, not 1 (one).
  • So, January is represented by 0, through to December being represented by 11.
  • You need to remember this when using the Date.getMonth() method;
  • And when creating a new Date() object with a constructor overload – e.g. var today = new Date(2018, 1, 21) to create a date representing 21 February 2018.
• A JavaScript Date object is internally represented as the number of milliseconds since 1970-01-01 00:00:00 UTC;
• But the object itself uses the local timezone of the system running it – e.g. In Melbourne, Australia it returns a date/time of UTC+1000 during Australian Easter Standard Time and UTC+1000 during Australian Easter Daylight Time (during daylight savings).
• If you try to manually calculate the current UTC time and set a Date object to that date/time, then the value of date and time is the same as UTC, however, the Date object still returns the local system timezone.
• The JavaScript Date.getTimezoneOffset() is non-intuitive and returns the opposite of the UTC timezone offset sign.
  • For example: If the local timezone is UTC+1100 then getTimezoneOffset() returns “-660” (that minus 660 minutes).
  • Why?
    • The definition of the method is: “The getTimezoneOffset() method returns the time zone difference, in minutes, from UTC to current locale (host system settings).”
    • In other words: it subtracts the local timezone offset (including the offset sign) from UTC.
      • Example: UTC+1100 timezone = UTC – (660 minutes) = 0 – 660 = -660 (negative 600).
      • Example: UTC-500 timezone = UTC – (-300 minutes) = 0 – (-300) = 300 (positive 300).
      • If you’re wondering how 0 – (-300) makes a positive, that’s fundamental maths: subtracting a negative value from another value adds those 2 values together.
      • The zero in the examples is the timezone offset of UTC.

With that in mind, consider this scenario:

• We have a system that stores date/times in the database as UTC.
• We have a web front-end that works with JavaScript date.
• We want to pass a date from the front-end to a server-side API that records the date in the database.

I’ve seen the following:

• A JavaScript Date variable representing the current local date and time is created:

  • var localNow = new Date();

• We want to JavaScript Date variable representing a ‘StartDate’, and we want to assign the current UTC date/time to it:

  • var startDate = new GetUTCDate(localNow);

  • See below for the GetUTCDate() function.
• We need to serialize startDate to JSON so send it over the wire to the API.

The problems with this are:

• ‘startDate’ may have a value that represents the UTC equivalent of ‘localNow’ but the actual ‘startDate’ JavaScript object still retains the local timezone offset.
• The JSON.stringify() method used to serialize a JavaScript object to JSON converts Date values to their UTC equivalent time (remember the internal representation of a Date object is an offset representing a UTC time);
  • So what ends up happening is the ‘startDate’ value represented in the JSON is actually the UTC time plus or minus the local timezone offset.
  • For example:
    • If the current local time is 21 February 2018 at 10:00am, then ‘the startDate’ JavaScript object has the value: “2018-02-21 10:00:00.00000 UTC+1100”
    • But the string/value for returned by JSON.stringify(startDate) is: “2018-02-20 23:00:00.00000 UTC” (11 hours earlier).

 

The following is written in a TypeScript:

// Takes a Date set to the local date/time, and return a Date representing the equivalent UTC date/time.
public static GetUTCDate(localDate: Date): Date {
  //UTC+1100 returns -660 (negative). Remove offset from local time to reach UTC. 
  //However, [local - (-offset)] = [local + offset], therefore equation is [local + (-offset)] which = [local - offset]
  //UTC-1100 returns 660 (positive). Add offset to local time to reach UTC.

  // NOTE: This still produces a Date object with local timezone offset
  let offsetMinutes = Math.abs(localDate.getTimezoneOffset());
  if (localDate.getTimezoneOffset() < 0) {
    //Ex: GMT+1100
    return new Date(localDate.getTime() - (offsetMinutes * 60000));
  }
  else 
  {
    //Ex: GMT-1100
    return new Date(localDate.getTime() + (offsetMinutes * 60000));
  }
}

Running Example

If you’re using Internet Explorer or there’s just a black window below, here’s the link to the code (and I suggest using a “modern” browser – Chrome and Edge work): https://stackblitz.com/edit/js-date-gotchas.

 

 

 

Other things to consider:

• If you want to store just a date (no time component) in a database, you cannot perform any locale conversions if it is stored as UTC.
  • Why? Let’s assume you want to convert the UTC date to the date in Timezone UTC+1100 AEDT (Melbourne, Australia). There are actually 2 dates this can convert to. To understand, look at it from the point of view of the local time we want to convert to:
    • In Melbourne, for any local time from midnight to 10:59:59am the equivalent UTC time is the day before (e.g. if the local date is 21 February, then UTC date is 20 February);
    • However, for the remainder of the day – 11:00am to 23:59:50pm – the UTC date is the same as the local date (i.e. both dates are 21 February).
• Think about how you want to handle dates that are timezone neutral. That is a date that remains the same regardless of where in the world you are. For example, a date of birth usually does not care about where in the world the person is born, nor the timezone.

 

I recommend adding these types of comments when writing code:

• Classes: A brief description of the class purpose.
• Functions/methods: A brief description of what the method does. It’s also good where possible to provide descriptions of the expected parameters and return value if applicable.
• Properties: A brief description of what the property is for.
• Most code has some logical grouping as it flows. Add a one or 2 line comment before each section describing what’s happening.
• If you write a complex piece of code/algorithm/fluent method chaining, add a description of what’s happening. Sometimes it’s difficult to determine what’s happening from the code alone.

Why is commenting code good?

• Put yourself in the does of someone who has to change the code later. Comments help other developers (and often yourself) understand what is happening, and what is supposed to happen.
• Comments are helpful in debugging errors, where the logic of the code may not match the expectations set out in the comment.
• Comments help other developers determine if a method or class is something they can use in their own code.

I’m writing unit tests in xUnit and have the following example asserts:

Assert.Equal(5, results.Count);
Assert.Equal(0, results.Where(r => r.MatchResult == ComparisonMatchResult.InvalidDonorAllele).ToList().Count);
Assert.Equal(1, results.Where(r => r.MatchResult == ComparisonMatchResult.Potential).ToList().Count);
Assert.Equal(4, results.Where(r => r.MatchResult == ComparisonMatchResult.Specific).ToList().Count);

However, xUnit gives me warning squiggles and messages like this:

When I Google for the warning to find out more I come to https://xunit.github.io/xunit.analyzers/rules/xUnit2013.html.

The problem is that page – nor any other page I can find so far – tells me why I should not use check collection sizes when there are zero (0) or one (1) expected elements. Why are there specialised assertions for these 2 specific cases? Why am I penalised for writing code in what I feel is a consistent and, I believe, easier to read way?

The moral of the story for developers: if you’re going to tell someone they’re doing it wrong, please also tell them why they are wrong and why the alternative is better.

Post Status: Draft/Under Development

This post is being written in conjunction with a piece of work dealing with JavaScript dates.

Draft last updated: 21 February 2018

---

Things to remember about JavaScript Dates:

• JSON.stringify() in JavaScript will serialize a date to UTC.
• Month numbers start at 0 (zero) in JavaScript, not 1 (one).
  • So, January is represented by 0, through to December being represented by 11.
  • You need to remember this when using the Date.getMonth() method;
  • And when creating a new Date() object with a constructor overload – e.g. var today = new Date(2018, 1, 21) to create a date representing 21 February 2018.
• A JavaScript Date object is internally represented as the number of milliseconds since 1970-01-01 00:00:00 UTC;
• But the object itself uses the local timezone of the system running it – e.g. In Melbourne, Australia it returns a date/time of UTC+1000 during Australian Easter Standard Time and UTC+1000 during Australian Easter Daylight Time (during daylight savings).
• If you try to manually calculate the current UTC time and set a Date object to that date/time, then the value of date and time is the same as UTC, however, the Date object still returns the local system timezone.
• The JavaScript Date.getTimezoneOffset() is non-intuitive and returns the opposite of the UTC timezone offset sign.
  • For example: If the local timezone is UTC+1100 then getTimezoneOffset() returns “-660” (that minus 660 minutes).
  • Why?
    • The definition of the method is: “The getTimezoneOffset() method returns the time zone difference, in minutes, from UTC to current locale (host system settings).”
    • In other words: it subtracts the local timezone offset (including the offset sign) from UTC.
      • Example: UTC+1100 timezone = UTC – (660 minutes) = 0 – 660 = -660 (negative 600).
      • Example: UTC-500 timezone = UTC – (-300 minutes) = 0 – (-300) = 300 (positive 300).
      • If you’re wondering how 0 – (-300) makes a positive, that’s fundamental maths: subtracting a negative value from another value adds those 2 values together.
      • The zero in the examples is the timezone offset of UTC.

With that in mind, consider this scenario:

• We have a system that stores date/times in the database as UTC.
• We have a web front-end that works with JavaScript date.
• We want to pass a date from the front-end to a server-side API that records the date in the database.

I’ve seen the following:

• A JavaScript Date variable representing the current local date and time is created:

  • var localNow = new Date();

• We want to JavaScript Date variable representing a ‘StartDate’, and we want to assign the current UTC date/time to it:

  • var startDate = new GetUTCDate(localNow);

  • See below for the GetUTCDate() function.
• We need to serialize startDate to JSON so send it over the wire to the API.

The problems with this are:

• ‘startDate’ may have a value that represents the UTC equivalent of ‘localNow’ but the actual ‘startDate’ JavaScript object still retains the local timezone offset.
• The JSON.stringify() method used to serialize a JavaScript object to JSON converts Date values to their UTC equivalent time (remember the internal representation of a Date object is an offset representing a UTC time);
  • So what ends up happening is the ‘startDate’ value represented in the JSON is actually the UTC time plus or minus the local timezone offset.
  • For example:
    • If the current local time is 21 February 2018 at 10:00am, then ‘the startDate’ JavaScript object has the value: “2018-02-21 10:00:00.00000 UTC+1100”
    • But the string/value for returned by JSON.stringify(startDate) is: “2018-02-20 23:00:00.00000 UTC” (11 hours earlier).

 

The following is written in a TypeScript:

// Takes a Date set to the local date/time, and return a Date representing the equivalent UTC date/time.
public static GetUTCDate(localDate: Date): Date {
  //UTC+1100 returns -660 (negative). Remove offset from local time to reach UTC. 
  //However, [local - (-offset)] = [local + offset], therefore equation is [local + (-offset)] which = [local - offset]
  //UTC-1100 returns 660 (positive). Add offset to local time to reach UTC.

  // NOTE: This still produces a Date object with local timezone offset
  let offsetMinutes = Math.abs(localDate.getTimezoneOffset());
  if (localDate.getTimezoneOffset() < 0) {
    //Ex: GMT+1100
    return new Date(localDate.getTime() - (offsetMinutes * 60000));
  }
  else 
  {
    //Ex: GMT-1100
    return new Date(localDate.getTime() + (offsetMinutes * 60000));
  }
}

Running Example

If you’re using Internet Explorer or there’s just a black window below, here’s the link to the code (and I suggest using a “modern” browser – Chrome and Edge work): https://stackblitz.com/edit/js-date-gotchas.

 

 

 

Other things to consider:

• If you want to store just a date (no time component) in a database, you cannot perform any locale conversions if it is stored as UTC.
  • Why? Let’s assume you want to convert the UTC date to the date in Timezone UTC+1100 AEDT (Melbourne, Australia). There are actually 2 dates this can convert to. To understand, look at it from the point of view of the local time we want to convert to:
    • In Melbourne, for any local time from midnight to 10:59:59am the equivalent UTC time is the day before (e.g. if the local date is 21 February, then UTC date is 20 February);
    • However, for the remainder of the day – 11:00am to 23:59:50pm – the UTC date is the same as the local date (i.e. both dates are 21 February).
• Think about how you want to handle dates that are timezone neutral. That is a date that remains the same regardless of where in the world you are. For example, a date of birth usually does not care about where in the world the person is born, nor the timezone.