There is a big difference in coding a small project with just a couple of lines of code and engaging a big project that can end up to become thousands lines of code. Projects of this size require planning and good management to prevent it to become a big nightmare.
Of course planning is crucial even for smaller projects, but when you are dealing with bigger ones this becomes even more important, planning is vital to succeed with the project. Without it the risk is great that you miss deadlines, end up with poor code due to the fact that you didn’t really know what exactly you needed to code or where you were going, in one word you are at risk to end up with a completely buggy mess. Software engineering is a must as far as I am concerned and I know that most programmers feel the same on this issue.
As this is a very important part in programming I decided to write an article on this topic where I will address the different issues to think about before you jump to the actual coding
I want to already now say that I feel that this article will become a monster in terms of its length and will most likely be split into two parts.
Planning and Running an Application Project
If you think that there is a methodology or project life cycle that is best, then I’m sorry to say this but I do not believe there is one ultimate and perfect path to follow. However, there are a number of things that I believe you should consider doing for your project. I’ll list them quickly here and explain them more thoroughly in later sections in this article. This is an order I use for most of my projects when it comes to developing web applications, however in which order you follow is up to you, in other words you choose the order that suits your project best.
- Before you even begin, sit down and think about what you really are trying to build. What is you goal with the project? Who is going to use your application, with other words, who are you target audience? Many good projects fail because nobody took the time to check whether there was a interest in such an application.
- Break down you application into components. You should try and think of what parts or process steps your application have. How will those components work and fit together? Sometimes coming up with scenarios and storyboards can be helpful for figuring out this part.
- Now when you have a list of components needed. Check which of them are already available. If you find a module that has that functionality, consider using it. This search should not only be conducted within your organization but outside as well, as there are a lot of preexisting components available especially in the open source community. Decide on what code you must write from scratch and estimate how big that job is.
- Take decisions on process issues, somehow this is forgotten sometimes. Decide for example on coding standards, directory structures, development environment, documentation level and standards, management and version controls, and task allocations to members in the coding team.
- Throughout your process, remember the importance and usefulness to separate content and logic in your applications. I will come back to this later on.
- Build a prototype based on the previous information, show it to a user group and repeat this throughout the process.
- Make any optimizations that you think are necessary.
- Throughout your project don’t forget to thoroughly test it!
- userage
- user_age
- userAge
- Files, complete files/scripts or include files
- Functions
- Classes
- Block of code within a script/file or function
- Complicated code or hacks
Reusing Code
A mistake that is often made by programmers is simply that they reinvent the wheel, rewrite code that already exists. When you have found out what components you need don’t forget to look for what’s available before you begin with the development. Sometimes coders rewrite functions accidentally because they didn’t check the language manual to see whether an existing function already supplies the functionality that is needed. You should always have a manual close to you whether it’s available online or in a book form.
Another issue that pops up from time to time, with programmers who come from a different language background is that they might be tempted to write wrapper functions to essentially rename the already built in functions available to match the functions in the language they are familiar with, this is by some called syntactic sugar. I see this practice as a bad idea, which in most cases will make the code harder to understand. It also slows down your code.
In my opinion this practice should not be used, if you are dealing with a new programming language you should learn to use it properly without adapting the syntactic sugar. Avoid it!
If you find the functionality you require is not available in the language, you basically have two choices. If it’s relatively simple, you can choose to write your own function or object. But if you are looking on building something far more complex, you should not be surprised if somebody else already has already built it, which you can use. If you don’t find a component that work exactly as you want but is still similar, you can save a lot of time to by looking at the source and modify, add or as an example to build your own.
If you end up building your own functions or components, consider making them available for the rest of the developers after you are done. Of course this cannot always be done, especially if you have a component that unique and is a major part of the application you are selling.
Write Maintainable Code
This is another problem that amazingly too many programmers have. This is usually caused by programmers writing the code in a hurry. Getting started on the code and getting the project done fast is in most cases considered as more important than planning it first. Some pull it off, but most realize that by investing some time in the beginning would save them from a lot of problems further down the road.
Coding Standards
If you work in an IT organization you know that most of them have coding standards, guidelines to the house style for choosing variable and file names, guidelines for commenting, for indenting code and so on. If you are coding on your own or in a small team, this issue can easily be underestimated and forgotten. The importance of must not be overlooked! Your team and project might grow and you’ll not only end up with a big mess but also a bunch of programmers that cannot make any sense of any of the existing code.
Coding Naming Conventions
The goals with adapting this are basically to make the code easy to read. If you define variables and functions sensibly, you should practically be able to read the code as you would read an English sentence, or in most cases as pseudo code.
To make the identifier names easy to remember, if your identifiers have a consistent format it will become much easier to remember what you called a particular variable or function later on.
Variable names should describe the data they contain. If you are storing somebody’s age call it age and don’t use anything cryptic or that doesn’t make any sense like calling it sunSpins. You also need to find a balance between length and readability. If we take the same example as before, storing the age in age_of_the_user is perhaps more informative but it’s a lot more to type which increases the risk of a typing error. If you think about it this doesn’t really add that much more value.
You also have to make a decision on capitalization. Do you want all your variables and functions to be in lowercase, uppercase or a mix where the first letters of words are capital letters?
A practice that is commonly used is to have all variables in lowercase and all constants in uppercase.
There is a bad practice some programmers are using, for a reason that is beyond me, and that is to use the same name for two variables but with different capitalization, for example age and Age. Why you shouldn’t use this I hope is very obvious for you reading this.
Also try to avoid using capitalization for amusing purposes, like naming a variable CrAcK. No one will remember how this amusing scheme works later on.
Decide on a scheme to use for variables names that contain several words.
Whichever you choose doesn’t matter, what matters on the other hand is that you try to stick with the style you chose. Another thing you might want to do is to set a limit on how many words a variable name can contain.
When it comes to the function names, the same steps are to be followed. The only difference with naming functions is that they should be verb oriented, describe what they do. This makes the code a lot easier to read. A function that calculates the priceshould logically be named calculate_price and nothing else that doesn’t make sense.
A method you might want to use is the module-naming scheme, what you do is basically add a prefix to the function name with the name of the module. For example if you have a shopping cart you might want to begin the names of the functions with cart_ to make it clearer for what purpose that function is used, in addition to what it does.
Commenting Your Code
A very important part of coding is to not forget to comment! Of course this should not be overdone but instead programs should be commented to a sensible level. The trick is to know what a sensible level means. I typically consider adding a comment to each of the following things:
Each file should have comment saying what it is, who wrote it, when it was last edited and what it does.
You should comment on what the function does, what input that is expected and what it returns.
You should in your comment include the purpose of it, the methods should have the same type
of comments as any other function.
I find it very useful to write the code by beginning with some pseudo style comments than continue with filling in the code for each section. My initial file might look something like this:
# Ask for input
# Validate input
# Report result
I know a lot of people that also find this method very helpful, and the good thing is that by the time you filled out the file or function with code it’s already commented.
Everyone has at some point coded some quick hack or something complex that took a lot of time to code. It’s very vise to leave a comment on these code snippets explaining why you chose to solve it in this way and what it does. Doing this you won’t find yourself some time later hitting your head against the wall trying to find out what the hell that was supposed to do.
Some might think that they’ll come back and comment the code later on, which most likely won’t happen unless you have more self discipline and time than I do. If that is the case I have to give you credit.
Indenting
You code should be indented in a sensible and consistent manner. Indenting makes your code easier to read and a lot faster to understand, as it helps you see what code belongs together much faster.
Any code block that belongs inside a control structure should be indented from the surrounding code to make it easier to spot it. The indention should be noticeable but don’t exaggerate. I usually use a level of three spaces of indention on all projects. I don’t like using tabs as it tend to take up a lot of space on the screen, but that’s just a personal taste.
Another issue is how you lay out your curly braces:
if (condition)
{
// Do something…
}
//B
if (condition) {
//do something
}
The above examples are the two most common. Which one you end up choosing is up to you; as long as you are consistent and avoid confusion it doesn’t matter.
Leave a Reply