Make Your Code Easy To Read
When writing code for a program, it's easy to fix all of the bugs and have it compile correctly, but making it easy for another human to read it is much harder. Here are some steps & tips that will help you to improve your code's readability.
Steps:
- Use white space. Skip lines between code that does different things, and use spaces after a semicolon and commas. This will make your code look cleaner and easier to read.
- Indent inside curly braces. This makes it so that it's obvious that a chunk of code is separate from another. This can help when writing a long method. Indenting inside if statements and loops will make it easy to read. This technique is called nesting that is it shows a chunk of code is "nested" within another chunk of code, and allows the reader to easily follow the nesting pattern.
- Write descriptive comments. Assume the person reading your code knows nothing about what it's supposed to do. Your
comments should explain every step of the way. All of your advanced, confusing, or complicated algorithms should be well
commented. Also, try to describe what purpose the code has.
For example, instead of writing "add one to variable," say why this is important in the code, as anyone can see it is incrementing the variable, e.g. "increment the number of page hits by 1". - Don't use long object names. Avoid names that contain unneeded words that can be omitted. Make your names short so that they don't get confusing. Also, make your code "self-documenting" by creating descriptive object name that describe what their purposes are.
- It may also be useful, particularly if you are writing longer pieces of code, to add a few lines of comments at the top of the software, giving information and a date for revised versions of the code (version history), along with the author of the code and date it was initially written.
- Comment often. Write comments for nearly everything you do and whenever you can. That way, you won't need a Vulcan interpreter to read your code if you decide to make a new version.
Tips:
- If you want to comment a large chunk of text, use "/*" to start the comment and "*/" to end it. Then, you don't have to write "//" on every line. (Note that making comments may be different in other languages).
- Making your code easier to read will also help you debug your own program, making it easier on yourself.
- Constant variables should be in all caps, with words separated by an underscore. Regular variables should have the first letters of each word be capitalized, omitting the underscores.
- Find your style of writing code. There are a variety of styles you can use, such as the following examples: myVariable, MyVariable, myvariable, MYVARIABLE, My_Variable, MY_VARIABLE, my_variable, my_Variable, My_variable, and more. Make sure you assign each style to a specific type such as MY_VARIABLE for constant variables and myVariable for regular variables. Just make sure that you stay consistent through style. You don't want to end up having both myVariable and MY_VARIABLE constant variables.
CSS
h1 { }
h1#logo
{
font-size: 2em;
color: #000;
}
h2 { }
h2.title
{
font-size: 1.8em;
font-weight: normal;
}
On using this technique, you can easily find out different heading tags for CSS. This technique is also useful if you are sharing code or working on a large site where you are using the same heading tags such as (h2) in numerous places, since you can give style to each one separately and not to worry about child classes inheriting attributes from the parent class.
Similar techniques are used for paragraph tags, anchor tags, & any other tag that requires multiple classes to look correct in every occurrence.