3 Core Principles to Write Clean Code

In this post I’m going to show you how to write code that is easy to read, maintain and understand.

Introduction

Coding is for humans.
Clean code is the art of writing code that humans can understand.

Any fool can write code that a computer can understand.
Good programmers write code that humans can understand

Martin Fowler

We’ll walk through 3 core clean coding practices:

  1. Stay Native
  2. Maximize Signal to Noise Ratio
  3. Write Self-Documenting Code

1. Stay Native

native

Avoid using one language to write another language via strings.
Do not use strings in C#, Java etc. to generate

  • JavaScript
  • HTML
  • XML
  • CSS

dirty_code

2. Maximize Signal to Noise Ratio

signal

Signal is code that follows the TED rule. It is Terse, Expressive and Does one thing.

Noise is anything else:
• Repetition
• Huge Classes
• Long Methods
• High Complexity
• Excessive Indentation
• Unnecessary Comments
• Poor Naming

3. Write Self-Documenting Code

self-documenting

Understanding the original programmer’s intent is the most difficult problem.
Code’s author intent should be clear. Well written code is self-documenting and can reduce and hopefully eliminate the need for comments or external documentation like Javadoc or Wikis.

Self-documenting code does 4 core things:

  1. Expresses author’s intent clearly
  2. Uses layers of abstraction (code navigable through different levels of details)
  3. Is formatted for readability
  4. Favors self-expressing code over comments

References

Cory House

Robert C. Martin

CSR and MDS: 4 Steps to get the Best from both Worlds

I’m going to show you how to create a CSR (or JSLink) script that works with and without MDS and follows coding best practices.

Scenario

Both CSR (Client-Side Rendering) and MDS (Minimal Download Strategy) are new concepts in SharePoint 2013.
CSR lets you control how your list data is displayed using Javascript.

CSR

MDS improves rendering performance where large parts of the page do not change, providing a more fluid navigation experience.

MDS.png

Problem

The problem is that CSR works fine with MDS only on the first page request or after a refresh. As soon as the user switches between views or navigates around and then comes back to the original page, the CSR customization vanishes and the default rendering takes place again.

I’ll try to explain what happens here.
When the page is first rendered, the MDS system receives the custom script for the first time and puts it in a list of already executed scripts. When subsequent pages are requested, MDS checks its own list of already executed scripts and will simply not execute them again.

However you want the CSR script to execute every single time… So, how to achieve that without disabling MDS feature and keeping its performance gains?

Solution

The following CSR script comprises 4 steps:

  1. Following Coding Best Practices
  2. Addressing MDS Garbage Collection issue
  3. Addressing MDS Script Reload issue
  4. Making it work without MDS as well
Type.registerNamespace('Client');
Client.Project = Client.Project || {};
Client.Project.Templates = Client.Project.Templates || {};
Client.Project.Functions = Client.Project.Functions || {};

Client.Project.Functions.Display = function (context) {
var currentValue = context.CurrentItem.MyFieldInternalName
if (currentValue > 0) {
return currentValue;
}
else {
return '<span style="color:red">' + currentValue + '</span>';
}
}

Client.Project.Templates.Fields = {
'MyFieldInternalName': {
'DisplayForm': Client.Project.Functions.Display,
'View': Client.Project.Functions.Display,
'NewForm': null,
'EditForm': null
}
}

Client.Project.Functions.OverrideTemplates = function () {
SPClientTemplates.TemplateManager.RegisterTemplateOverrides(Client.Project);
}
Client.Project.Functions.MdsOverrideTemplates = function () {
var scriptUrl = _spPageContextInfo.siteServerRelativeUrl + "/SiteAssets/CSRScript.js";
Client.Project.Functions.OverrideTemplates();
RegisterModuleInit(scriptUrl,Client.Project.Functions.OverrideTemplates);
}

if (typeof _spPageContextInfo != "undefined" && _spPageContextInfo != null) {
Client.Project.Functions.MdsOverrideTemplates();
} else {
Client.Project.Functions.OverrideTemplates();
}

Let’s examine the above script in more details.

1. Following Coding Best Practises

Define your own namespaces to avoid polluting the global one.

Client.Project = Client.Project || {};
Client.Project.Templates = Client.Project.Templates || {};
Client.Project.Functions = Client.Project.Functions || {};

2. Addressing MDS Garbage Collection issue

Register your root namespace to avoid MDS Garbage Collection to wipe it away during page transitions.

Type.registerNamespace('Client');

3. Addressing MDS Script Reload issue

Register your script to have MDS system reload it every time, even after a page transition.

var scriptUrl = _spPageContextInfo.siteServerRelativeUrl + "/SiteAssets/CSRScript.js";
RegisterModuleInit(scriptUrl, Client.Project.Functions.OverrideTemplates);

Append a revision number to the JSLink attribute of your custom field definition and update it at any script change/deploy in order to prevent browsers from using the old cached version.

<Field
      ID="{ce3d02df-d05f-4476-b457-6b28f1531f7c}"
      Name="MyFieldInternalName"
      DisplayName="My field display name"
      Type="Number"
      Required="FALSE"
      JSLink="~sitecollection/SiteAssets/CSRScript.js?rev=1.0.0.0"
      Group="My Custom Group">
</Field>

4. Making it work without MDS as well

If MDS is disabled the _spPageContextInfo object is undefined in the script inline code.
If that is the case there is no need to register your script and you can call the template override function directly.

if (typeof _spPageContextInfo != ‘undefined’ &amp;amp;amp;amp;&amp;amp;amp;amp; _spPageContextInfo != null) {
   Client.Project.Functions.MdsOverrideTemplates();
} else {
   Client.Project.Functions.OverrideTemplates();
}

References

Wictor Wilén

Martin Hatch

Technet

Why SharePoint 2013 Calculated Columns will Save your Life – Filtering Lookup Values

I’m going to show you a no-code, out-of-the-box, simple way to create a filtered lookup column which will work with SharePoint 2013 On Premises and Online.

Scenario

A client comes up with the following requirement:

We have two lists

  • List A (Title, IsSelectable)
  • List B (Title, Lookup to List A)

We want to filter lookup values so that only selectable items are shown to users to choose from.

List A and B

Solution

Use a calculated column in List A and write the formula like this:

=IF(IsSelectable,Title,””)

Tip: if you receive a syntax error try and replace the “,” (comma) with “;” (semi-colon). Site regional settings can affect the syntax used in SharePoint.

List A and B - Filter Applied

Pros

  • Out-Of-The-Box only
  • No InfoPath forms
  • No SharePoint Designer
  • No JavaScript/JQuery/XSLT
  • No Visual Studio code

Time to implement: 3 minutes.

Cons

If you should change an item to be no longer selectable then in the list where you have used it its value disappears. That behavior could be ok for most scenarios but be aware of it.

Alternative Solutions

There is a solution on Codeplex which creates a custom site column to handle this. However that solution is not compatible with SharePoint Online because created using server side code.

References

MSDN

StackExchange

Balestra

April Dunnam