Programming Guidelines: How to program

Define Programming Languages

First select a programming environment to work on, the coder must know the limitations, cons and pros of the language, and must know how to use the language. If he don’t know what can be done with this programming language it is useless to use the language.

Look for already done code / libraries / classes

Check the codebase for already created code / libraries / classes to use them in the new projects and to improve the project’s coding. If codebase don’t have the functions and classes which you are seeking for, create your own files and classes to store the functions or group of functions, as they will keep the specific code separate from the original code, and also can be re-used, in any other website for the same functionality.

Finalize the Design and CSS before you go for real coding.

For small projects or simple HTML pages, finalizing the design and CSS before development of the website will save time of development, and for large projects, although it is not possible in some cases that we get a design completed with all the CSS needed, as we may need new elements and CSS classes as we proceed developing the website. But it is wise to complete as much design and CSS elements as possible before starting the development, as this will save the time in future.

Keep URLs short

It is a good practice that while developing the websites, try keeping the URLs short, so they should be easy to remember by the users, and they are helpful in Search Engine Optimization.

For example http://mywebsite.com/users/profile/ compared with http://mywebsite.com/new_users/2009/user_profile_public.html

Thumbnails

Thumbnails are necessary in site performance and load time of the pages, always try to use thumbnails. If required create the thumbnails from Adobe Photoshop, or in case of large websites where users will be uploading the images by their own, creating thumbnails on the fly and saving them on the server is also a great practice.

Variable Names 

1. All variables / identifiers that represent words or phrases must be English words or phrases.
2. Use small caps for single word identifier/variable
3. Capitalize the first letter of interior words in all multi-word identifiers.
4. Avoid using all upper case characters in an identifier. (unless it is a CONSTANT)
5. Avoid all identifier abbreviations in your programs. When necessary, use standardized abbreviations or ask someone to review your abbreviations. Whenever you use abbreviations in your programs, create a “data dictionary” in the comments near the names’ definition that provides a full name and description for your abbreviation.
6. All identifiers should be pronounceable (in English) without having to spell out more than one letter.
7. Use Spaces before and after (, ), ‘,’ , and commas.
8. Breaking code in to 80 Column lines. It will be easy to read by other programmers, and programmers don’t have to use the horizontal scrollbars to read the code.
9. For statements that are too long to fit on one physical 80-column line, you should break the statement into two (or more) lines at points in the statement that will have the least impact on the readability of the statement. Best is to use breaks immediately after low-precedence operators or after commas.

Commenting

1. Always put comments before a function or the part you have worked on describing the change done, and the reasons. Also use at least one line space between the real code and comments.
2. Don’t put wrong comments i.e.
   $a = 10; // setting the variable ‘a’ value to 12;
3. Don’t put unnecessary comments (same like above) as this is very simple, and will waste the time of coder in future. Also it will be hard to maintain the comments on slight change in the code. E.g. changing value of $a to something else and then modifying the comments.
4. If there are comments at the beginning of the file, describing the functionality covered, and who last worked on the file, should be updated on every change. Outdated comments are always creating problem.
5. Comment as you go. Keep writing the comments along the programming. Leaving comments to be written on the end will consume a lot of time, and management will not allow the time line only for writing the comments for the whole project.
6. Write comments with proper English and avoid telling jokes or using slang, sexy words in comments, as at some point others will surely be reading your code.
7. Write comments that describe blocks of statements rather than individual statements.
8. Use comments to prepare the reader for what is to follow. Someone reading the comments should be able to have a good idea of what the following code does without actually looking at the code. Note that this rule also suggests that comments should always precede the code to which they apply.
9. Comments should describe a routine’s limitations, assumptions, and any side effects.

Keep Code Simple

Keep the code simple, so everyone can understand the code, these also include the variable names and commenting sections of this document. This will help editing the code later by any other programmer. i.e. ‘ternary operator’ (my_variable = (x > 10)?”foo”:”bar”;) is not understood by all the programmers who have shifted themselves from ASP to PHP or any other language which is not similar to C, so a simple if statement may increase couple of lines, but is far easy to read by large number of programmers. (It didn’t meant that I am not in favor of ternary operator, if it can be educated then that’s best)

Identify the true problem

Before start fixing any problem, make sure you have identified the real problem, as it happened many times when there is some problem; developers start fixing that without going to identify it first, thus wasting time.

There are number of ways to identify the problems.

(i) Looking from the beginning of the process, and

(ii) going back step by step from the problem out to start of the process.

(iii) One other way is to create a separate test case, just to check the solution you need to implement, as this will save the time and fuss of working in a thousand line of code. When you get stuck, stop, build the SMALLEST test case that proves the point, and then proceed ahead with the regularly scheduled programming.

Learn to prototype.

The two ends of error are to go spec out an extensive solution without a proof of concept. OR to build the entire technology feature complete before proving it out. Prototypes don’t do everything; they just show you are headed in the right direction before you get to the wrong location.

DRY

Don’t Repeat Yourself or DRY. Dry software doesn’t just copy/paste/edit when it can be encapsulated. Without getting ultra OO you can benefit from DRY software development. Reuse moves edits to one location, makes life-cycle support better and often starts to make short term development faster and more stable.

Errors Logs

Many servers and websites keep an ‘Error Log’. These logs tell the time and date and the file/line number in details including what was the error. Always look for the error logs on the server and local machine while developing any website, as they store important information, and they are helpful in identifying the error and fixing them.

Don’t consider a solution as a final procedure,

If you can create a simple solution then please do so, as there is always place for improvement in the code.

These are not the complete guidelines for programming, and there is a lot of space for improvement. This documents will keep evolving.