Writing "Good" Code

Good code is code that works for the target users and can be maintained by you and others well into the future. Think of future developers as another set of users. They need documentation to help them get into the code and make updates, add new features, and fix defects.

Think of it this way; you've been assigned to get the lights working in an old building. Would you want to wander around in the dark until you discover what was wrong? What would you pay in this situation to have someone hand you the manual for the building that describes all the wiring with maps of the corridors and rooms? (makes it less like a horror flick).

Examples

Examples of levels of code documentation:

• Proj4JS - This is actually not a browser-based JavaScript library. It is for a server-side JavaScript system. It is a great example of how not to write code with single small functions in each file, all named the same name! I wrote a Java program to convert this to JS and even add some documentation to the code.
• jQuery - while a very popular library with good online documentation, this is an example of know to write code if you only want a few people who live in JavaScript to understand your code. There is little documentation in the code, poor variable naming, and the code is written in a very unique way.
• Chart(js) - a huge file with very little documentation but appears to work well.
• hammer - the name is a little annoying because it does not describe what it does but otherwise, this library is very well documented and uses the JSDoc standard.

Document the code for maintenance!

Provide a separate folder for your documentation that is outside your code.

• Requirements specification: Update
• Design documentation:
  • Overall structure of the folders and other stuff (i.e. how does the data in your map get updated?)
  • Design for the web site: typically this is pretty minimal for web apps but is important regardless
• Implementation:
  • Notes on what worked and what didn't
  • Documentation in the code (HTML, JS, and CSS)
• Testing
  • Defects: especially those still outstanding
  • Defect metrics?
• Maintenance
  • Releases with changes for each fix
  • Change management?
    • Changes require approval from stake holders?

Web Site Files

Web sites typically have the following structure (not really a standard but you'll see it a lot).

• Image folder for icons and other images
• css for CSS files
• js for JavaScript include files
• HTML Files

As your web site grows, you'll want to add additional files for groups of web pages. At each level, you can provide a "ReadMe" file to help the user know what is in each file. This can also help to document the state of files that are in development.

Other files should NOT be in the web site as they will actually be available on the web! Files for documentation, original geospatial files, and original artwork files (i.e. Illustrator and PowerPoint) should be managed elsewhere. I recommend having a GoogleDrive folder with these files.

Backups: Make sure to make backups! A good practice is to have an external drive that you backup EVERYTHING to and then take the drive home and copy it to another computer.

File Names

Remember to name your files so it is easy to determine what is in them (XYZZY is cute but does not help).

Code Files

"Code" includes the HTML, JavaScript, and CSS files. While the web is still a bit of the wild west, we need to help move it toward a more professional development environment.

Code files should rarely, if ever, contain a single function or style. Functions should be grouped in files with names that describe their contents. The best approach is to put the functions into a related class and then name the file the same name as the class. Files should also not be so large as to make it hard to find code in them.

Separate your "development" and "released" code. Development code is yours, comment and make notes but they are for you. Your released code is different and you need to think of it as any other product, without appropriate documentation it will be unmaintainable

Code files should include a file header at the top that lets the reader know what is in the file. Code should be divided into related "blocks" and each block of code should include another header explaining its content. Functions in JavaScript, styles in CSS files, and sections of HTML code should also have headers to explain what each individual section of code does. This is especially true of "interesting" code.

Of course, all variables, class names, "id"s and other identifiers should be good names that describe the associated element.

Code Documentation Standards

Most compiled languages have documentation standards. Python has one emerging and JavaScript has one as well, "JSDoc". This is now used in CanvasMap and other libraries. If there is no standard, make one up! It is far better to have documentation that is standardized than to have everyone documenting code in different ways. I recommend:

JavaScript

Use JSDoc for function headers with at least the "@" definitions. These can be parsed to create function references.

Add file headers to each file:

/***************************************************************************************
* CanvasMap Class
*
* This class implements a full dynamic mapping system with a layer list and a status
* bar.  The user can add tool icons as desired.
*
* The elements for a CanvasMap are held in an array, 
* @module CanvasMap
***************************************************************************************/

Use long line comments to divide sections of code:

//***************************************************************************************
// Private functions for managing stickiness
// These are here just to make the code simpler to add stickiness
// Stickiness is when the elements "stick" to one of the sides of the window.
// Elements can be sticky and either move or size with the right side or bottom of the window.
//***************************************************************************************

Add function headers above each function and make those available outside the class "public" or "protected":

/*
	* Add a layer to the map.  The layer will be on top of other layers
	* @public
	* @param NewLayer - CMLayer object to add to the map
	*/

Add inline comments in the code as needed for someone who is not you to quickly understand the code.

HTML

Create header blocks just as we would for programming code:

<!---------------------------------------------------------------------------
 This is the HSU Web Map.  It contains:
 - Raster tiled background
 - Point layer for all the point data in the legend/menu
 - Polyline layer for the polyline data (bus routes, accessible routes)
 - Polygon layer for the buildings
 
 The web page contains two "sliding" DIVs: the MenuBox and the InfoBox.
 These are controlled by the MenuButtons and InfoButtons respectively.
 ----------------------------------------------------------------------------->

Sections of code can be divided as in JavaScript:

<!---------------------------------------------------------------------------
1.2 Style sheets
----------------------------------------------------------------------------->

Use long comments to mention what the next block of code includes

<!-- Footer at the bottom of the page with the Info button –––––––––––––––––––––––––––––––––––––––––––––––––– -->

And shorter ones with key lines of HTML:

<!-- Menu and Info Box styles -->
<link rel="stylesheet" type="text/css" href="css/SlideBoxes.css"/>

<script src="js/SearchUtil.js"></script> <!-- search utility -->

CSS

CSS should contain the same comments as other code and it may even be more important because CSS is hidden from us and can be very complicated (which I do not recommend).

File header for CSS can be formated in a similar fashion to JavaScript except that we don't have the "//" operator for comments:

/*
* These are styles for the elements of a CanvasMap.
* Change these as you desire to change the appearance of the elements in the CanvasMap
*
* The styles are named for the elements that they are used with.  The names are just
* "CamelCase" here (upper and lower case) where they are all capitols in the CanvasMap.js file.
* There is a full list of these elements in the referece.
*
* CSS originally by Chris Muhl, maintained by Jim Graham
*/

Sections of code can be divided up:

/*****************************************************
* Classes for the map footer
******************************************************/

Styles can have headers just as functions in JavaScript:

/* 
* The item in the list containing the layer checkbox, icon, and name 
*/

And inline comments can be critical to helping someone edit the file quickly:

margin: 10px 4px 0px 0px; /* top, right, bottom, left */

Coding Practice

In the early days, we wrote "spaghetti code" because did not have good coding practices or structures like modules and classes. Then, we wrote more"structured code" which was easier to support and this set us free to write larger programs. Then, we create Object-Oriented Programming (OOP) which further "encapsulated" our code so we could write even more code and keep it relatively easy to maintain.

Below are some good practices to follow that will make your code relatively easy to maintain:

• Do not "chain" function calls or variable definitions.
• Have only one "return()" statement and put it at the bottom of your function (just add "if/else" to remove the ones further up in a function).
• Don't create a function in a function call. This is heavily used in JavaScript and has it's place but you'll want to minimize it.
• Don't try to create the most complex line of code ever! Instead, go the other way and spread out your code with comments so it can be debugged and maintained.
• At the same time, don't add extra white space or you'll be scrolling forever
• Keep the size of your files between 100 and 1000 lines of code.
• Using "i,j,k" for loop variables is OK but otherwise, use good variable names that describe the variables contents.

Additional Resources

• JavaScript: Bad Practices
• The Difference Between Excellent, Good and Bad JavaScript Developers