Monday, March 16, 2015

5 Conventions that can make our life easier

All my life I longed to work in a place were a list of rules were glued to the wall, saying what you can and cannot do, should or should not not, in your code. Doesn't have to be anything fancy like design patterns, life-cycle management, or unit testing, but the basic things that everyone should know, and keeping them in mind so they don't forget.

Because of the professional path (I guess), I was never told how to create my variables, what to name my methods, and to what extend I should use comments.
More and more I think that conventions are great because they allow everyone to do things in similar ways, ways that are recognized as good practice, and that will keep individuals from straying away and doing things "their way". Conventions are also good simply because we can create an organization-based list of rules so that everyone in the team speaks the same language and takes into consideration the same challenges (defaults for creating classes, pages, libraries, etc.).

With this in mind, I am going to lay down a few of this simple practices that help my everyday.

1. Write in English
This one goes out to those who, like me, don't speak English as their natural language.

Writing in English is great because, first, it is a convention that if everyone follows, everyone will be able to read each one's code. Other than that, well, it will be easier for you to sell your code if you want to, or just have someone read it to help you. In a globalized world, this is becoming a must, tough we sometimes forget or get lazy about it.

And yes, this applies to code comments as well!

2. Follow Naming Conventions
There are good generic conventions for variables, methods, classes and constants.
For each individual programming language, there are also some specifications.
E.g. for .NET, lowerCamelCase for variables and UpperCamelCase for methods:

float myWidth;


class Raster;


Namespaces can also follow a convention, e.g.

For PowerShell functions, it makes more sense to use the [Verb]-[Noun] convention for methods.
E.g. Add-DocumentToLibrary

If we run "get-command", we can see some common verbs, such as Get, Test, Update, Set, Start, Stop, New, and many others. Some may like his verb/noun signature just enough to use it on other languages.

3. Avoid spaces
Coming from an MS-DOS background, I am still used to keeping my folders with no spaces and low amount of characters. It is just easier for a script to go there without having strange characters in it, or requiring the usage of commas. Specially for the web, spaces are a huge no-no.

Some examples:

- Folders "\\computer\c$\file share"
\\computer\c$\file share VS \\computer\c$\fileShare

When you try to copy a link so you can send it to someone, the first link will break due to the space

- Websites and pages
http://site/site 1 vs http://site/site1

In some scenarios, the first url will have its space replaced by a "%20", which basically looks ugly.
In some other cases, the link may break as it did for the previous example

My advise is don't use spaces for websites, folders, or libraries.
For pages or views, sometimes it can make sense to separate two or more words. For those cases, use the hifen , "-", not the underscore, "_".
By doing this, you are also potentially improving SEO.

- SharePoint columns
If you worked with SharePoint, you know how bad can your columns' internal names look like
e.g. "Procedure Name" --> "Procedure_x0020_Name" or "Procedure%5Fx0020%5FName" (web)

Overall in SharePoint, it is a good practice to create something with a friendly name first, and then go back and change it (websites, lists, pages, views, columns).
It is also preferable to query "internal names" or "guids" instead of "display names", since the later are susceptible to change.

4. Refactor
It is common to hear, "if your code is more than one page long, it is too big".
I am not a fan of absolutes, but the idea is that if your method is becoming too big, than it probably does more than what it is selling.
It is usually good to split a function into several different functions in order to improve things such as:
- Reusability
- Unit testing
- Readability

5. Leverage helper methods
Common functions should go to a special place, where they can be easily reused.
Quite often you will end up doing repetitive code so you will want to refactor those "DownloadDocument" or "GetItem" methods to keep them generic enough so they can be reused, and at the same time, being able to copy them to other projects with little or no changes at all.

What many people are not aware of is the danger or creating static methods in static classes.
This is usually done so we can call a method without an instance of a class, but it goes down to what the method does. If you are relying on shared data, you may be in trouble.

No comments:

Post a Comment