Project Code Style Expectations

This page records some of SamR's expectations for the code in MIST (and elsewhere). Code includes Javascript, css, ejs, SQL, and similar things. You do not need to update all of your code to match these requirements now, but you should make sure that any new code follow them, and, when you have some free time, you should strive to update previous code to match these requirements.

General Issues

Start Every File with an Introductory Comment. It's nice to be able to know what file you think this is, and what purpose the file serves.

Indent Consistently. We use two spaces as our indentation. Not tabs. Not single spaces. Not four spaces. Why? It's small enough that text does not get too wide. We use spaces instead of tabs because tabs are not rendered consistently.

Comment Your Code. Your peers will not necessarily understand your code. Functions need a preliminary "What does this do?" comment. (The six P's are not necessary.) Internals can benefit from "here's what we're doing here" comments.

Cite. If you take non-trivial approaches from somewhere, you have a responsibility to cite that location. I've seen some really strange design decisions and often hear "I found it somewhere".

Don't Duplicate Code. If you find that you are programming with cut-paste-change, whether in terms of functions or styles, you should extract the general code.

Group Related or Similar Code in Sections. It's nice to be able to find things that go together. It also helps your reader.

When Appropriate, Alphabetize. At times, people will be looking at your code on paper. Alphabetical order makes it easier to find things. You'll find that I do a moderate amount of alphabetization in the files I create, and it bothers me when you break that alphabetization.

Don't Put Single-Case Code in a General Library. I saw this with some CSS sheets in which one page out of twenty had a particular image that needed to be formatted differently.

When Possible, Write General Code. I know that this contradicts some common agile practices. But if you can predict that your code will be used in related situations (or that we'll have to handle some related situations), you may want to start by generalizing.

Additional CSS Issues

Check Pages on Multiple Browsers and Multiple Window Sizes. We have ready access to at least seven different browsers: Chromium and Iceweasel on Linux; Chrome, Safari, and Firefox on Mac; and Chrome and Firefox on Windows. (I don't care if IE doesn't work.) When you add a non-trivial stylistic element, check it on all of them, using different window sizes.

Use Identifiers and Classes. There are cases in which we say things like "All text input fields should be formatted this way". (And yes, I'm guilty of that, too.) But we really don't mean it. Classes help us set styles for just the things we want.

Don't Reuse Identifiers. Identifiers are supposed to be unique.

Comment Your Code. I'm repeating this because our CSS is generally uncommented. Try to explain why the CSS that you have there is there.

Avoid float. There are some instances in which float is useful. But we clearly overuse float. And floating elements tend to make other elements more difficult to write.

Use the Right Units. CSS provides a wide variety of ways to specify sizes. Think about what is most appropriate, and sometimes that means letting the browser figure things out. I've seen buttons whose size is specified as a percentage of the page width. That means that when the page shrinks, the button shrinks, even if the text stays the same size. That can lead to some really bad formatting.

Additional Javascript Issues

Use "Conventional" Indentation Patterns

control-structure {
  code
} // comment

Additional SQL Issues

Indicate Primary Keys.

Indicate Foreign Keys.

Make Keys Unique.

Make Keys Auto Increment.