Improving SEO For Your Jekyll Site

Photo: Victor Hughes - unsplash.com

Search Engine Optimisation (SEO) refers to how you increase the quality and quantity of organic traffic to your web site. There are many articles and tools available covering best practices. I would suggest this article to start with and then research the various points. Getting your sites SEO right is critical. It will increase your chances of people finding your content in search engines.

Working on a new site for Open Energy Market has made me investigate how well this blog is optimised. One of the first things I wanted to improve was its SEO score on web.dev. Before making the changes in this post the score started at 49.

I have written before about how I build this site with Jekyll. After a little Jekyll SEO optimisation research, I discovered the Jekyll SEO Tag gem. The gem automatically generates recommended SEO meta tags for each page and post in your site. The following are some of the tags created as part of the configuration and content of the site:

• Page title. This will be generated with the site title and/or description appended.
• Page description. If you use a description tag in your forward matter this will be generated otherwise it will be skipped.
• Canonical URL. The fully qualified URL to your post or page.
• Next and previous URLs on paginated pages. When generated on a paginated page, the gem will include the URLs for the next and previous pages.
• JSON-LD Site and post metadata for richer indexing. This moz.com article covers the use of this tag,

See the Github documentation for a full list of tags that can be configured and generated.

To install jekyll-seo-tag you need to add the following to your Gemfile:

$ gem 'jekyll-seo-tag'

Next, you need to add the plugin in your sites _config.yml:

plugins:
  - jekyll-seo-tag

And finally you need to add the following on the line before your </head> tag:

{ % seo % }

(Without the spaces between the brackets and the % character. Shown as such here to prevent Jekyll from compilling the command) e.classList.remove(“lazy”); Once these settings are added you can run:

$ gem install jekyll-seo-tag

That will install the plugin. Once you start your site back up and view the page source you will see the tags and the content generated by the plugin. On re-running web.dev my SEO score had increased to 92. This is without adding specific keywords or any other changes.

I will write up in a future post other optimisations for SEO as I decide on the ones to implement. For now, the little work it took to add this useful plugin is well worth it.

If you have any suggestions or questions about this post then please contact me via twitter or email.

Typing For Developers

Photo: JF Martin - unsplash.com

There are a lot of articles about the skills that developers need to build a great career. One thing that always seems to be missing is the importance of typing. Every so often an article will appear but it is never promoted with the same importance as other core skills.

It seems to be one of those things that are assumed for a developer. You spend all day in front of a computer and so you can type, right? Wrong. I have seen even very experienced developers who two finger type or type looking at the keyboard. What is the impact of not having good typing skills and what can you do about it?

The answer to both of those questions is “a lot”.

The impact is on productivity. Not so much how much you deliver but more about your hands keeping up with your brain. When you are in “the zone” and the solution is flowing the last thing you want is for you not to be able to transfer it from the brain to file. If you look at the keyboard to type then you can not possibly know where on the screen you are typing. This can become even more of a problem if you pair program regularly. “Typing Performance Anxiety” is a real thing. We have all been there in front of someone else when our existing typing capability seems to halve.

Being able to type fast is one part of typing well. The other part is using the keyboard to prevent the break of flow in typing. When you take your hand off the keyboard to use the mouse to perform a task you lose track of your thinking. This doesn’t mean you have to switch to Vim (or Emacs) to become a fluent typist. It does mean that you need to learn the keyboard shortcuts for your application. Most applications even allow you to change the shortcuts. This means you can align them between applications and only have to know a limited set. You will gain considerable time and prevent considerable pain by only using the keyboard.

The final area to be impacted is accuracy. If you can type well then you are able to type accurately. This can save considerable time in correcting your output.

So, how can you improve your typing? In an age where everybody wants to self improve there is a range of sites that can help. keybr seems to be a simple tool that can help as does typing.io and Speedcoder.net. The last of these is actually geared to writing code as well. I personally have found that it doesn’t matter which tool you use. It is more about the discipline of practice. In fact, when I made a concerted effort to improve my typing years ago I would just copy text from a document in a side by side set up. I did it for 15 minutes a day for a month solid and I noticed a great improvement. After that first month, I would still practice a couple of times a week.

The final thing I have to say about typing is to find a keyboard that works for you. The keyboards that come as standard these days vary in quality. Different people prefer different travel and layouts. You may benefit from trying a mechanical keyboard. Or you might find that the shallow travel of laptop keyboards works better for you. Do not be afraid to experiment.

If you have any opinions, suggestions or questions about my views here then please contact me via twitter or email.

Readable Code Part 5 - Wrapping Up Code Readability

Photo: Unsplash

After a short interlude for an Easter holiday, I wanted to bring to an end my series on readability. This post will look at a few peripheral things to keep in mind when developing readable code.

First up is formatting. Formatting covers a few areas. Line width, Tabs vs Spaces and syntax flow all fall under this.

var user = UnitOfWork.GetRepository<User>().GetAll().Where(u => u.Name.ToLower() == lockedUser.Name.ToLower()).SingleOrDefault();

Vs

var user 
    = UnitOfWork
        .GetRepository<User>()
        .GetAll()
        .Where(u => u.Name.ToLower() == lockedUser.Name.ToLower())
        .SingleOrDefault();

And

public static bool IsFalse(this bool b)
{
    return b == false;
}

Vs

public static bool IsFalse(this bool b)
{
  return b == false;
}

Tabs vs Spaces has been discussed to death and I have never understood the problem. Pick one as a team and stick to it. Splitting your code vertically or horizontally makes no difference to the compiler. But, it can make it easier to read when structured vertically by statement. This is especially helpful with more fluent API’s as shown above. As I have covered in previous posts, the key is consistency. This consistency should be applied across projects and be enforced company-wide. This will help in onboarding developers, code reviews and team productivity. When interviewing you should make a point of asking to see their style guide. If they don’t have one then suggest you would like to lead the development of one if successful. If you don’t agree with some small points in an existing guide then adapt or decide that the use of spaces is just too unreasonable.

Consistent formatting choices lead to agreeing on a code line length. In years gone by a lot of organisations would work to 80 characters per line. This stems from hardware limitations. Today most people have at least Full HD screen resolutions, if not 4k. I would still argue that a shorter line length makes for easier code to read. It also means that you can reduce context switching by having multiple files open in an editor side by side. A lot of editors try and automatically wrap long code lines across multiple lines. This makes code inconsistent and hard to read. I tend to set my max character count per line to 100.

Next I want to cover deep nesting. Deep nesting makes code very hard to read and is normally a code smell. By deep nesting, I mean code such as:

public void foo(object[] args)
{
    if (args != null)
    {
        foreach(var arg in args)
        {
            if (arg != null)
            {
                if(typeof(arg) == String)
                {
                    foreach (char c in arg)
                    {
                        Console.WriteLine(c);
                    }
                }
                else
                {
                    Console.WriteLine(arg);
                }
            }
        }
    }
}

In most cases there is a better way to structure the code. Just breaking the nests down into methods improves the readability.

public void foo(object[] arguments)
{
    if (arguments != null)
        return;

    foreach(var argument in arguments)
    {
        if (argument != null)
            continue;
    
        if(typeof(arg) == String)
            OutputByCharacter(argument);
        else
            Output(argument);
    }
}

private void OutputByCharacter(string argument)
{
    foreach (char character in argument)
    {
        Console.WriteLine(character);
    }
}

private void Output(object argument)
{
    Console.WriteLine(argument);
}

This leads on nicely to Code Grouping. Grouping and ordering of methods and functions by the use of white space should be done in the same manner you would group your paragraphs in prose. Again agree on how you will do this and enforce it. There are different grouping approaches I have seen such as:

• Grouping by access modifier. This results in all public methods being together and then all protected methods and then all private methods.

• Grouping by use. This means that public methods are generally defined first along with protected methods. Private methods are generally defined under the first public or protected method that uses it.

I like the second of these approaches. It means that you do not have to scan to the bottom of a source code file to find a private method. It is usually within a few lines of the code that calls it. This means it aids reading and reduces (but does not prevent) context switching. There doesn’t seem to be a best practice around grouping.

Finally, I want to cover source code file organisation. This can sometimes be governed by the framework you use. If it is not then you need to organise files in logical groupings and namespaces to make finding files simple. There are different ways to do this and even approaches such as Clear Architecture. If you have to create your own structure then group related items. One project I have worked on has a Services directory. Within that directory is over 300 business logic and domain related service classes. It is hard to navigate and to find code. Don’t do that.

So that’s, mostly, what I have to say about improving code readability. It comes down to two main things:

• Write code that is clean, logical and easy to digest. Code is written in a language. Language is a method of communication. Either you or someone else will read your code many times over its lifetime. You do not want to confuse or hide the meaning of the code. Think about Unix and how some systems developed in the 1970s are still in use. That code will have been read thousands of times. Are you happy that your code could survive like that?

• Any supporting readability guides, formatting or project structures should instil consistency. Work with your team to agree on what you feel is a good level of readability and stick to it. Build checks into your code reviews. Encourage your team if they commit code in a way that is not in line with the guide. Think of your code as words on pages which are your files in the book that is your project.

If you have enjoyed this series or have any opinions around the idea’s I have outlined in these posts please contact me via twitter or email. I would certainly like to discuss them in more depth.

Readable Code Part 4 - Extending Languages For Readability

Photo: Nadine Shaabana - Unsplash

In this next post in the code readability series, I want to cover the use of language extensions. This is a powerful feature of a lot of modern languages. From C based languages through to dynamic languages such as Python. But, it is almost never mentioned in relation to code readability. Usually, we use extension methods to wrap Type utility methods or create project specific functionality. Here I want to look at taking it a bit further to improve readability at a solution level.

Modern languages use a limited set of operators and keywords like their forerunners. A number of current languages all have between 30 and 40 reserved keywords. Given the amount of research undertaken in language design, it amazes me that as a profession we use such limited and unfriendly syntax to develop code. I might argue that we have actually made it harder than it once was.

Take for instance:

IF ((A.GT.B).AND.(B.LT.C)) THEN

END IF
     
IF ((C.GT.D).OR.(B.EQ.C)) THEN

END IF

That is FORTRAN syntax. A language that was first released in 1957. Compare this to:

if((a > b) && (b < c))
{

}

if((c > d) || (b == c))
{

}

The above could have been taken from any C language tree derived language from the last 40 years. FORTRAN’s design goal was “to create the first ‘user-centered’ programming language.” It focused on “the reduction of mechanistic instructions into simple English commands with algebraic formulas. Its language focused more on the problem the person using the computer wanted to solve than on the machine’s operations.” How often do you feel that the language you use has similar goals? Given that we are pushing more people to the role of a programmer the question must be why are we repeating the obfuscation in each language in each new variant?

Back to readability. How much easier is the FORTRAN code above than the C derived language code? Considerable I would argue. While if statements are easy to read and generally make sense, no one would argue the same for the C language && or || operators. && is the most confusing as in most English based languages, & is shorthand for ‘and’. But, in C derived languages & is an operator to obtain the address in memory of a variable. I assume that this operator was defined before the operator for ‘and’. For most people && does not relate to shorthand for ‘and’ and neither does || for ‘or’. I suspect most people would find reading the FORTRAN versions easier.

So how could we use extensions to improve the readability? Using C# and its Extension methods we could end up with the following:

if(a.IsGreaterThan(b).And(b.IsLessThan(c)))
{

}
	   
if(c.IsGreaterThan(d).Or(b.Equals(c)))
{

}

We can achieve this prose like readability by using the following, simple extensions.

public static class BooleanExtensions
{
     public static bool And(this bool firstCondition, bool secondCondition)
     {
         return firstCondition && secondCondition;
     }
     
     public static bool Or(this bool firstCondition, bool secondCondition)
     {
         return firstCondition || secondCondition;
     }
}

public static class IntegerExtensions
{
    public static bool Equals(this int number, int comparisonValue)
    {
        return number == comparisonValue;
    }
    
    public static bool DoesNotEqual(this int number, int comparisonValue)
    {
        return number != comparisonValue;
    }
    
    public static bool IsGreaterThan(this int leftValue, int rightValue)
    {
        return leftValue > rightValue;
    }
    
    public static bool IsLessThan(this int leftValue, int rightValue)
    {
        return leftValue < rightValue;
    }
} 

This is an improvement over && and || and simplifies the reading of > and <. Most developers will say that this is a minor improvement. That it adds little benefit to code readability. But what if you apply the same logic as you build your project to solution and domain logic and entities? What you would end up with is a solution specific Domain Specific Language (DSL). This should make the code simple to read and more importantly understand. You can essentially change your chosen language to be simpler to read and work as you need. You are no longer constrained by the limited operators and keywords it has decided to implement. This enforces consistency throughout your code base. There is far reduced developer centric variations. It also means it is easier to automate your style guide. A secondary benefit unrelated to readability is that we can apply tests. We can write simple code once and move on to composing logic and objects.

If you implement the idea’s here then you should follow the same rules that I outlined in the previous post. Your extension method/function names should follow a consistent theme. If you create a IsNullOrEmpty string extension then an extension that checks for Null or Empty List’s should be named likewise. You should also consider how you structure your extensions. They should exist at the lowest level possible. If your language supports generics then use that to handle common extensions across types.

If you have any opinions around the idea’s I have outlined in this post or would like to discuss them in more depth then please contact me via twitter or email.

Readable Code Part 3 - Code Asset Naming

Photo: Markus Spiske - Unsplash

This third post on code readability is about code asset naming. This includes variables, objects and function/method naming. There are many different views on this subject and it can be contentious. But, I will outline the reasons for the rules I follow as I go through the article.

The first thing that I want to highlight is that all languages have style guidelines. .Net has C# Coding Conventions and the F# style guide. Python has PEP 8. The Elixir community went so far as to take their style guide and enforce it with a build task. If your stack doesn’t have one then the community most certainly will have defined one. Find the one applicable for your language, read it and stick to it. Define its usage in your project documentation. If need be, automated its application with supporting tools. Issues like name casing and tabs vs spaces will be governed on your languages style guide. The following set of recommendations are to be used with the applicable style guide.

The most important thing is that you make your code asset names as obvious as possible. There is never a reason to use a single letter/symbol variable name for variables:

double d = 10.;
int i = 5;

What is d? What significance does it have in the method or function it is used in. There is no way to know the answers until you read through more of the surrounding code. Remember from previous posts that we want the code to be read like prose. So having to search for the meaning of d will break your ability to read the code fluidly.

(Actually, there is a single reason to use such a naming convention and that is when implementing mathematical/scientific notation. However, you should limit it to a single class or namespace and not use notation as domain specific variable names.)

You also do not want to use a name that requires you to use a comment to explain it:

int height = 21; // Height in Centimetres 

string name = "Bob"; // The managers first name

So, how should you name your variables and objects? Simple, in a clear way that reveals what the purpose is or what it is referencing:

int heightInCentimeters = 21;
string managersFirstName = "Bob";

You should not worry about longer variable names as they provide clarity. We are not working with limited memory and clarity beats brevity. Intellisense is available in all editors and resolutions are much higher these days on screens as well. While from habit I tend to stick to 100 characters per line that stems from the start of my career. On the opposite end of the same spectrum, do not make your variable names overly long either:

int anIndexCounterUsedToTrackTheNumberOfEmployeesInAList = 0;

This is not useful and can be reduced to the following while still providing the required clarity:

int employeeListIndexCounter = 0;

For most of the languages I have worked with, there is almost no reason to add a language type *fix to a name. With strongly typed languages especially, you add no value with:

bool isLoadedBool = false;
bool boolIsLoaded = false;

Over:

bool isLoaded = false;

While dynamic languages imply their type from the assigned data there is still no reason for the *fix. What if the following:

intDivisor = 10

Became:

intDivisor = 10.57654

By changing the data assigned you have now made the variable name invalid. This nicely brings me onto the next naming issue I have seen a lot, lying naming. Never name an asset in a way which misleads, confuses or plain lies to the reader over its intention. If you have a collection of objects call it a collection:

var results = _someObject.GetResults(calcInputs);

Could be redefined as the following to clarify its purpose:

var resultsCollection = _someObject.GetResultsCollectionFrom(calcInputs);

If you change an object or variable’s purpose then change the variable name to reflect it.

// Changed the method call to return a List<Results>

var resultsList = _someObject.GetResultsListFrom(calcInputs);

Across your objects, you should try and adopt a consistent naming approach. This is confusing and inconsistent:

_someObject.Remove(item); 
_someOtherObject.Delete(thing);
_aThirdObject.Bin(record);

Would be better as:

_someObject.Delete(item);
_someOtherObject.Delete(item);
_aThirdObject.Delete(item);

I’ve found that by using strong parameter naming you can massively improve readability.

var employeeId = 100;
var employee = db.Employees.FilterBy(employeeId); // public void FilterBy(int employeeId)


// Update data

employee.Name = "Fred Smith";
employee.Age = "55";

db.Employees.Save(employee); // public void Save(Employee employee)

db.Employees.Delete(employee); // public void Delete(Employee employee)

As you can see above, this code becomes extremely easy to read. Once a developer has worked on the code base for a short while they will become quicker due to the predictability of the method or function naming. This shows the lack of need to include the Type in the naming. The following doesn’t really offer any benefit:

db.Employee.FilterByEmployeeId(employeeId);

I see a lot of naming like the above. It slows the ability to read the code down due to duplication. In most cases Verb(parameter) is almost always good enough. In fact, it can be quite a nice feature of some languages when implementing fluent API’s:

var employee = new Employee().Add(name).Add(age).Add(employeeAddress);

Adding solution and domain naming conventions tend to result in specific naming patterns becoming obvious. The Clean Code community suggest that you can mix in solution and pattern related suffixes to your naming conventions. Including the full design pattern name is akin to including a type suffix. But, adding a clear identifier can be helpful in understanding the code dependencies and responsibilities, such as:

var managerFactory = new ManagerFactory();
var manager = managerFactory.CreateNewManager();

What you do not want to do is confuse mixing in access modifiers such as the following:

// Should be called EmployeeFactory as the fact it is an abstract class is obvious from the access modifier

public abstract class AbstractEmployeeFactory
{
}

public  class ManagerFactory : AbstractEmployeeFactory
{
}

var abstractEmployeeFactory = new ManagerFactory(); 

We should be mindful when naming objects and methods/functions of the languages namespace functionality. The namespace should be seen as a container in which your naming makes complete sense. As an example, taking the above code you would not expect to find a method that is destructive. A Factories namespace should only contain objects with methods that result in the creation of objects.

The last thing worth remembering is that your reputation is based on your code. So with that in mind, it is always best to leave the humour to team events and one on one conversations.

var result = employeeRepository.Kill(employee); // No

var result = messageRepository.Post(letter); // No

var omgHowOld = employee.CalculatePensionAgeFor(employee); // No

Just like insulting, rude or humorous comments, git blame will point to you. As you get older you will appreciate the impact on the way you are viewed.

So those are my thoughts on naming. They come from reading a great deal on the subject and real-life experience. Again, the purpose of this series is to instil that readable code is instrumental to the success of any project. By adopting clean, clear and consistent naming conventions you will reduce the development effort of your project. It will ease the onboarding of your growing team. It will also improve your velocity and simplify business as usual changes.

If you have any opinions around code asset naming or the points made here then please contact me via twitter or email.