Maintaining Good Programming Standards

No matter what stage your company is in, having a set of agreed upon standards is key to a maintainable code base and an organized eco-system. Many companies attempt to do this, but fall short when the employees get lost in the process and end up steering away from the standards. Guilty as charged. So coming up with a standard that is difficult to deviate from is key. It should naturally make sense and be simple to follow.

And alot of that has to do with lowering restrictions. The more barriers you put up, the higher the chance that someone will get caught up in them, either knowingly or unknowingly. Standards sound like a fantastic idea regardless, but one must realize that they will dictate the way that your employees work from that point on and it will effect most aspects of a project from that point on. So if you're coding standards are 209 pages long and revised weekly by a legal team, then maybe you should start over.

you make your own problems

Writing down 100 rules to follow and then getting upset with 1 of them isn't followed isn't management. But many corporations find it to be so. So have your standards at most be 2-3 concise pages. Much easier to read, follow and to understand. And this is custom for each and every company. But the following guidelines might be able to help a bit in designing your own.

What should be standardized

More so than just code, anything from the way that you create and store files to the way that your company serves images should be standardized and documented in some shape way or form.

• File storage
• File naming convention
• CSS Syntax
• JavaScript Syntax
• Commenting structure

Let's take a look at each one of those down below.

File Structure

Keep your CSS and JS files in one location. That's it. Just one directory. This way, anyone that works on your project will know immediately where to add files. Having separate style sheets for example for an admin page may make sense at first, but only if you already know about this process. If you're coming in brand new, people are expecting you know add the files to the correct directory. If only you had an idea of that.

Now span that over the course of a year and several developers and you're going to end up with a headache. Storing a file, shouldn't require any extra thought. You shouldn't have the option of 4 places where it could "maybe" be, and then you just pick one. Reduce the complexity and everyone will have a much greater time.

CSS

There are a few elements in CSS that you begin to standardize. For one, the file naming structure. By default, there isn't any given recommended method for naming your resource files. So come up with one. For us, we have 1 file per "page", with the name of the file specifying the page. A page is defined as a similar grouping. For example, a wizard has multiple pages, but for the most part it's main look and feel is the same. So the following file would be the template file:

~/content/style/wizard.css

For more complex elements, such as the actual wizard steps, we also split those off into their own files.

~/content/style/wizard_step1.css
~/content/style/wizard_step2.css
~/content/style/wizard_step3.css

And again, this is our current standard. Everyone must find the one that works best for them. We've had great luck working with this particular method and our turn around time is very quick.

Typical Syntax Standards

If we're dealing with a programming language, you'll need some type of coding standards in place as well. Again, that's left to you and your corporate needs. Many times, coding standards comes down to a few things: "spacing", "case", and "indentation". Very commonplace and not very helpful in the grand scheme of things. An important thing to realize is that coding standards should be in place to help guide the developers and to help maintain as much as order as can be maintained with multiple people.

We don't feel that capitalization is the best use of time for anyone. The programmer normally has to reprogram themselves in a way in order to get comfortable with new syntax rules. And that either leaves them with a bad taste in their mouth, or, not following the standard. And soon after a project manager will jump in and make it his job to update all casing. Again, not the best use of time.

So instead of focusing on code at that visual level, you might have to dig deeper in order to come up with standards that will both save everyone time and that will not make the work tedious for anyone. For us, a big part of that comes down to variable naming conventions and define classes and objects for almost anything requiring local data transmission.

Serving Resources

If you're using a CDN, then have a procedure in place for using it. Different CDN's have different methods of managing content, so get familiar with it, and document it for your team. If you're not using a CDN, then also make that clear. You don't want to end up with a website that relies on using 3-4 CDN's in different places.

Focus on elements that will indeed benefit your corporate structure and that won't put off anyone. And keep it to a minimal. The more complex something is, the bigger the chance of error.