Overview
The principles and guidelines I recommend adhering to are going to be illustrated with examples to make the points clear. Some topics covered are the choice of programming languages and developer tools, KISS, DRY, modularity, documentation.
Recommendations
Have a sound judgement!
For most “things” there are no one-hundred-percent rules and this it the case for this guide as well. Some of the following principles are potentially contradicting each other in certain given situations, e.g. KISS and DRY. The most important thing now is to think for yourself and make adequate choices for each given situation, because most of the time guides cannot cover every possible (programming) situation.
Choose a reasonable language!
When facing a problem the first thing to do is to categorize it. In the programming world, you can face very different problems. You might want to build artificial intelligence or perhaps a webshop or maybe even contribute to an operating system or you want to simulate the heat distribution development inside a machine component. When confronted with a variety of choices, choose the best maintained and popular language(s). This increases chances for future usefulness and support from other developers.
Examples:
- If you want to simulate the heat distribution inside an engine you might want to choose a language that has been designed for simulation.
- If you are in France you better speak French.
- If you want to setup a (non-static) website or an online shop you need to learn server-side languages such as PHP or ASP and a query language for accessing databases: SQL.
- If you have some less special problems you can solve them by choosing a so-called GPL, which stands for general purpose language.
- Some prominent and always useful GPLs include C++, Java and Python.
- Figuratively speaking English would be such a general purpose language while French would be less of a GPL and more of a specialized language.
Master your tools!
Regardless of your preferred developer tools, what matters is that you know them inside and out. Developer tools are, but not limited to editors, integrated development environments (IDEs), debugging programs and modules, even the inspection tools of your browser.
Examples:
- Once having made a reasonable choice of a tool, stick to it!
- Know the shortcuts: knowing the shortcuts of your IDE can save you a ton of time (e.g. the “Step Over” shortcut of the debugging module).
- Know the nifty tricks: gather experience in using your tools and stumble upon your tools’ secrets.
- When missing a feature in your tool, it might still be there! Use the search engine first, e.g. search for “netbeans search and replace”.
- Not only when already being a seasoned developer: document your attained knowledge, it helps solidifying and prevents forgetting (or use a search engine and bookmarks).
Think before you act!
When confronted with a real world problem, the first thing you should figure out, what the goal or more specifically your goal is. Then verbalize in human words how you can reach that goal. Write it down and then think more specifically about each step. Unless you are very experienced and even then you might uncover serious design errors. Since you have not started programming yet, it does not matter, though. It is always easier to correct mistakes in earlier phases of development or developments.
Example:
The ultimate goal is to streamline the traffic in a big city. Considering the expectations, this might be a very hard task to tackle. Being true to the spirit of “divide and conquer” we will split this unspecified main task into more verbosely formulated subtasks:
- Get an adequately precise image of the road network.
- Consider traffic limitations such as traffic lights or construction sites.
- Consider the behavior of the drivers, their “source” points and their destinations.
- Simulate the traffic and try to alter the road network or traffic limitations.
Another basic concept of programming is recursion. We can look at these tasks as new main tasks for a team of programmers. Recursively we divide the new main task into subtasks and recurse again until we have very specific “small”, feasible tasks. Let’s look at the point: “Get an adequately precise image of the road network.”. It can be further split into the following substeps:
- Get the interstate highways.
- Get the freeways.
- Get the mainroads of big cities.
- Get smaller roads.
- Get farm roads.
Summing up: the recursive use of “divide and conquer” as well as thinking ahead in the planning phase of your project reduces later headaches by a lot.
Test your code in small chunks!
This one is easily understood and often times not taken seriously or for brevity’s sake neglected. Each time you design a new function or if it is a more complex one logical division of it, take the time and test it. Whether you have a deficient ten-line function or a deficient hundred-liner makes a big difference once it comes to fixing bugs.
In the long run having shorter testing periods really saves you time and nerves.
Avoid thinking by writing!
Please keep in mind that your programming responsibility for a program might be overtaken by someone else in the future. A good documentation of your code can help them or potential co-workers to understand your code. This might prevent new starts from scratch and thus huge economic damage.
Another even stronger benefit is that you can reproduce your own thoughts when rereading your notes again. Therefore, a good documentation is a must-have in both long-term and complex projects.
What, however, is considered a good documentation? This again depends on the context. If you have a rather short program, a well-commented source code might be sufficient. For “medium-sized” projects you might want to autogenerate a documentation with the help of Doxygen or similar. Huge projects require wiki pages, with rich media explanations and examples. An example for a good documentation of a huge project is the Qt-documentation (mainly C++-Framework).
KISS: Keep it simple and stupid!
Don’t make things too complicated. Solve your problem the easiest way possible if this does not violate a good number of other recommendations. If an easy, yet acceptably efficient solution (not limited to but also DRY, see below) and otherwise suitable is at hand, go for it. Do not make the mistake of creating a big confusing overhead, when it is not clear if its potential benefit is ever going to be redeemed.
Shamelessly copy what works!
Don’t get me wrong here. I’m not telling you to infringe copyright. What I mean by copying what works is that you should look at good code and good examples and learn from them. If you are allowed, copy whole functions and scripts and study them to improve your programming skills. If you understand WHY a well-written piece of code is good code, then your code design already improved a lot. Refactoring your own code can also save you a ton of time and potentially money.
DRY: Don’t repeat yourself!
A good rule of thumb is that you don’t want the (almost) same chunk of code appear more than once in your source code. There are different methods to circumvent repetition, e.g. using a common function with additional parameters for different results, such as createWidget(type) instead of createWidgetA() and createWidgetB(). Using callbacks (In doMaths(a, b, op), where op can be a function add(a, b), op is called callback function.) is another approach.
The benefit of not repeating oneself should be obvious: you have to write less code, therefore, your code is less prone to errors. It also can greatly increase the maintainability and extensability of your code, since a design change can be implemented by just altering one block of code instead of multiple blocks.
Be careful not to violate other principles, too, much though, such as KISS or contextually relevant principles. This often times can result in poor readability and poor performance (e.g. if you have a ton of seldomly used if-clauses).
Choose meaningful names!
Choose meaningful names for variables and functions. Instead of cryptic abbreviations such as sb_shcrt() use the full words to describe the functionality: showcart(). If you are trying to build structures, such as the HTML-structure of a website also make sure to choose class names that describe functionality instead of the position, e.g. choose class names such as widget-area instead of area-right.
Stick to patterns!
Not only when it comes to naming you should use the same naming patterns, but also when it comes to a lot of “structure-building”.
Examples:
- Make sure not to confuse ” and ‘, e.g. in PHP functions when e.g. echoing HTML.
- Always use the same jQuery closure pattern.
- PHP knows two different syntaxes to begin and end ifs and whiles, the colon and the braces syntax. Choose one and stick to it.
- There are different indent patterns, e.g. the “javascript indent pattern” (curly brace after function signature stays on the same line) and the “C++ indent pattern” (curly braces get their own line). Make sure you don’t forget any braces due to chaotic style.
Keep things readable!
It is not a good idea to save up whitespace to reduce the weight of a script. In the development version of a script, you should have a logical indentation and white lines to make it as comfortable as possible to read your source. Minifiers/compilers will optimize your script/program before the actual execution anyway.
Consider the context!
Before and while programming always consider the audience, the platform, the project’s priority and size and numerous other potential factors, such as a customer’s expectations. Since this recommendation might not seem very related to the process of programming itself, I will give you some examples why this assumption is not always correct.
Examples:
- Provided you don’t want to become “available for hire”, fulfilling a customer’s expectations is obviously the most important, regardless of which he has.
- If you program a website for an ordinary hairdresser, over-complicated work-intensive reinventing of the wheel is not necessary. Design a functional, nicely arranged website, where business hours are clearly visible and contact is easily accessible. Keep it simple here!
- If you, however, design a website for a multinational corporation, you might rethink the last point.
Take breaks and drink!
Literally. Just do it.