I've had the fortune of knowing a lot of professional and casual coders over the years--(well, "fortune" if you call banging your head against the table at dinner a delight, while computer scientists and engineers trade woeful stories about that unintelligible bit of code their group member turned in that week) and the one thing that never ceases to amaze me is how common the complaint of poorly documented code crops up.
Designers new to the world of web development have probably noticed by now that serious coders, like computer scientists or electrical and computer engineers detest having their work in C++ and Python compared to scripting and styling languages like HTML and CSS, but the truth is that there are a few common lessons that designers should learn from these more experienced coders that you won't get monkeying around with scripts and bits of code from common online source guides like W3Schools.
That said, let's talk about properly documenting your code.
Why is Documenting Your Code Important?
If you studied history in school, you know how important keeping a list of properly cited references is to the quality and efficacy of your research. Think of documenting code the same way.
By properly citing, organizing and explaining your work, you make sure that your collaborators or predecessors understand what you are doing, how you did it, and why. This knowledge is just as important for you as it is for them and your users. In addition, it's generally just a smart and friendly habit to keep up if you want people to take your work seriously and other web developers to look towards your work as a resource down the line.
So, how can you do this? How can you make sure that your code is easy to read and properly documented? You can start by assessing three things:
This probably looks like a small and unnecessary change, but scrolling through this .css file, I can easily see where every stylistic element of the webpage is stored. I can easily find the default fonts for the webpage, where any named image style properties are stored, or other style element properties, such as the header of a wordpress site or footer and how they are styled.
The Relative Affect
The relative affect of different scripted elements in Javascript or CSS is a bit more complicated; it refers to the reaction of a coded element to another element in the same document. Documenting the relative affect of a piece of code is important so that you or later users can easily peruse through your work and figure out why you made a decision about a particular element or function.
As an example of a code with a relative affect, let's look at the stylesheet again.
Below is code for a styled div:
Simple enough, but what on earth does all of this do? If you passed this code off to someone who had never seen it before, what would they think about it?
Let's make sure that other developers know what these do:
Readability
Now, all of this careful documenting means nothing if the reader can't figure out what your notes mean! You shouldn't feel like your eyes are assaulted by walls of text as soon as you look at the page, but you also shouldn't walk away from a file without any idea what the creator had in mind when they were coding.
General tips for readability:
Designers new to the world of web development have probably noticed by now that serious coders, like computer scientists or electrical and computer engineers detest having their work in C++ and Python compared to scripting and styling languages like HTML and CSS, but the truth is that there are a few common lessons that designers should learn from these more experienced coders that you won't get monkeying around with scripts and bits of code from common online source guides like W3Schools.
That said, let's talk about properly documenting your code.
Why is Documenting Your Code Important?
If you studied history in school, you know how important keeping a list of properly cited references is to the quality and efficacy of your research. Think of documenting code the same way.
By properly citing, organizing and explaining your work, you make sure that your collaborators or predecessors understand what you are doing, how you did it, and why. This knowledge is just as important for you as it is for them and your users. In addition, it's generally just a smart and friendly habit to keep up if you want people to take your work seriously and other web developers to look towards your work as a resource down the line.
So, how can you do this? How can you make sure that your code is easy to read and properly documented? You can start by assessing three things:
- Functionality
- The Relative Affect
- Readability
These are the 3 core rules that I stick to when I am coding for new projects in order to make sure that anyone who uses my code later as a resource exactly what I was doing, why, and how.
Functionality
Functionality refers to exactly what the code does. Let's look at a common css document, stylesheet.css .
html, body { font-family: Garamond, Times New Roman, Serif; font-size: 15pt; color: #000; background: #FFF; }h1 { font-size: 15pt; }h2 { font-size: 20pt; }h3 { font-size: 40pt; }img { border: solid 1px #CCC; }
#menu{ width: 10%; height: 30px; font-size: 14pt; font-family: Sans-serif, Helvetica, Arial; color: #FFF; text-align: center; border-left: solid 2px #0066FF; margin-bottom: 3px; float: left; display: block; margin-left: 0px; background: #333; padding-top: 7px; text-decoration: none; background: -webkit-gradient(linear, left top, left bottom, from(#668ECC), to(#80B2FF)); background: -moz-linear-gradient(top, #668ECC, #80B2FF);}
Here is a snippet of code from stylesheet.css. A few functions are self-explanatory. The html, body, header and img tags are easy to understand for novices to styling in CSS, so any further explanation of each of these elements is unnecessary.
Taken by itself, there's no problem with this bit of code. However, think about what you use your stylesheet for, or better yet what someone else might do with it. How much easier would it be if this bit of code was demarcated according to its individual functions?
html, body and header tags style the layout of the page. Let's make sure that users can easily find these tags, if that is what they want to modify in the document.
/*
DEFAULT STYLES
*/
html, body { font-family: Garamond, Times New Roman, Serif; font-size: 15pt; color: #000; background: #FFF; }
h1 { font-size: 15pt; }
h2 { font-size: 20pt; }
h3 { font-size: 40pt; }
/*
IMAGES
*/
img { border: solid 1px #CCC; }
/*
MENUS
*/
#menu{ width: 10%; height: 30px; font-size: 14pt; font-family: Sans-serif, Helvetica, Arial; color: #FFF; text-align: center; border-left: solid 2px #0066FF; margin-bottom: 3px; float: left; display: block; margin-left: 0px; background: #333; padding-top: 7px; text-decoration: none; background: -webkit-gradient(linear, left top, left bottom, from(#668ECC), to(#80B2FF)); background: -moz-linear-gradient(top, #668ECC, #80B2FF);}
This probably looks like a small and unnecessary change, but scrolling through this .css file, I can easily see where every stylistic element of the webpage is stored. I can easily find the default fonts for the webpage, where any named image style properties are stored, or other style element properties, such as the header of a wordpress site or footer and how they are styled.
The Relative Affect
The relative affect of different scripted elements in Javascript or CSS is a bit more complicated; it refers to the reaction of a coded element to another element in the same document. Documenting the relative affect of a piece of code is important so that you or later users can easily peruse through your work and figure out why you made a decision about a particular element or function.
As an example of a code with a relative affect, let's look at the stylesheet again.
Below is code for a styled div:
#menu{ width: 10%; height: 30px; font-size: 14pt; font-family: Sans-serif, Helvetica, Arial; color: #FFF; text-align: center; border-left: solid 2px #0066FF; float: left; display: block; margin-bottom: 3px; margin-left: 0px; padding-top: 7px; text-decoration: none; background: #333; background: -webkit-gradient(linear, left top, left bottom, from(#668ECC), to(#80B2FF)); background: -moz-linear-gradient(top, #668ECC, #80B2FF);}
Simple enough, but what on earth does all of this do? If you passed this code off to someone who had never seen it before, what would they think about it?
A little bit of thoughtful reasoning about the relative affect of each element styling this div can go a long way. Let's document the least obvious functions in this code.
margin-bottom: 3px;This could be an important design element. Maybe this margin keeps the div from falling off of the page, or disrupting another element in your design. In this case, letting others know this would be useful:
/* Keeps the menu from sliding off of the page */
margin-bottom: 3px; margin-left: 0px; padding-top: 7px;Easy enough. But what about those funny background styles?
background: #333; background: -webkit-gradient(linear, left top, left bottom, from(#668ECC), to(#80B2FF)); background: -moz-linear-gradient(top, #668ECC, #80B2FF);}There's a lot of stuff going on here. We have three different background styling commands which can be relatively effective and functionally important.
Let's make sure that other developers know what these do:
background: #333; /* Default background for browsers that cannot handle gradients */ background: -webkit-gradient(linear, left top, left bottom, from(#668ECC), to(#80B2FF)); /* Gradients for Mobile Web Browsers */ background: -moz-linear-gradient(top, #668ECC, #80B2FF);} /* Firefox compatibility */This is pretty simple demarcation; anyone who browses through the *.css file can tell what is going on in that div:
/*
MENUS
*/
#menu{ width: 10%; height: 30px; font-size: 14pt; font-family: Sans-serif, Helvetica, Arial; color: #FFF; text-align: center; border-left: solid 2px #0066FF; float: left; display: block;
/* Keeps the menu from sliding off of the page */
margin-bottom: 3px; margin-left: 0px; padding-top: 7px; text-decoration: none;
/* Default background for browsers that cannot handle gradients */
background: #333;
/* Gradients for Mobile Web Browsers */
background: -webkit-gradient(linear, left top, left bottom, from(#668ECC), to(#80B2FF));
/* Firefox compatibility */
background: -moz-linear-gradient(top, #668ECC, #80B2FF);}
Readability
Now, all of this careful documenting means nothing if the reader can't figure out what your notes mean! You shouldn't feel like your eyes are assaulted by walls of text as soon as you look at the page, but you also shouldn't walk away from a file without any idea what the creator had in mind when they were coding.
General tips for readability:
- Pay attention to white space. Don't use too much, but take advantage of the little brain breaks of relief one can get browsing through your page. I used a lot of space between major elements and line breaks within elements, as is evident in the #menu example.
- Keep your descriptions brief, but intuitive. Try not to write long-winded explanations of functions or relative affected elements
- Distinguish between the functions in your webpage. Think about your code the same way you think about organizing the layout of your page. Does this div belong in the menu section, or is it a part of the header? It may be useful to think about your code the same way that you would a decision tree, and organize different elements accordingly.
-Doni
No comments:
Post a Comment