Design Guidelines and Principles

Feature and Design Principles

MyMICDS was designed with a couple of ideas in mind to keep the website as stress free and low maintenance in order to ensure the website can run without constant maintenance. Because of this there are a few principles to keep in mind when considering new features.

Automation

Any features should generally be able to work without any regular, active maintenance. Some exceptions to this are April Fools.

Programming Principles

DRY, KISS, etc.

When programming, your code not only needs to function, but it should be consistent, maintainable, and adhere to DRY (Don't Repeat Yourself) and KISS (Keep It Simple, Silly).

Consistency

Ensure that if you do a thing a certain way, you do it consistently throughout the rest of the codebase.

For instance, if I write my functions like this in 99% of my codebase:

function doSomething() {
    // do stuff here
}

and I then write this:

function doMoreStuff()
{
    // do stuff here
}

It is inconsistent. While this is a relatively harmless example on its own, these inconsistencies can build up into creating a spaghetti code base. Also consider the way I named the functions. I didn't name the second function do_more_stuff or DoMoreStuff because it would have been inconsistent naming.

Readability

Code should readable, the variable names should be fairly easy to understand to anyone reading the code (including you 3 months later), and the purpose for everything should be understandable.

The first way that you can help create readable code is by properly naming variables and functions. For instance, it is more useful to use verbs in functions that nouns. registerAccount() is more descriptive than accountRegistration.

This blog post is a good read about writing clean JavaScript.

Use comments to help people understand why things are done the way they are, not what they do. For instance, instead of commenting:

// Set x to 1

Something like:

// Skip the first item, which is empty

is much more useful. This is not something that comes easily, but its good practice to start trying sooner rather than later.

Clean Code is a great book on how to achieve consistent readable code, but it isn't a must read unless you plan on making programming a career.

Linting

Linters help with maintaining this consistency. Using a predefined set of style and code quality rules, they automatically filter through a codebase and point out code that breaks these rules. The MyMICDS Angular repository uses TSLint with some special Angular-specific rules to keep our code clean.

Running TSLint

From the command line, run either npm run lint or ng lint. If TSLint finds any code that breaks a rule, it will display the offending line and file, including the rule it broke.

Some rules are automatically fixable, in which case you can add --fix to your command.

Editor Plugins

You will quickly learn that manually running lint commands is kind of a pain and easy to forget to do. Instead of this, most programmers install plugins in their editor of choice that highlight violating code directly in the editor and often provide auto-fixing tools.

• Atom: linter-tslint
• VSCode: TSLint
• WebStorm: Included by default (instructions for enabling)