Good practices for software development
Versioning and Commenting
Often left out due to time restrictions or enthusiastic programmers who want immediate results.
Adopt a common versioning and logging practice.
In MOPSI we use this:
// [module name] - [module description]
// owner: [owner name]
// version 0.0.0 - [d.m.yyyy]
//
// [programmer innitials]: [d.m.yyyy]: [what has been done]
// [programmer innitials]: [d.m.yyyy]: [what has been done]
// ........................................................
//
// [locked / unlocked]
Use a locking mechanism in order to let others know you are working on the file.
Automatic versioning systems also exist (svn, cvs, git).
Have a clear Goal in mind
Never begin coding without knowing exactly what you have to do.
If you want to create a function [ex: greatest common divider (gcd) of two numbers],
write an empty function first:
int gcd(int a, int b){
// TO-DO
return 1
}
Then a procedure with unit tests for the function:
void gcdTest(){
int failCount = 0;
int numTests = 2;
if(gcd(6, 8) != 2){
failCount++;
}
if(gcd(12, 30) != 6){
failCount++;
}
print("failed %d out of %d",failCount,numTests);
}
Finally, fill in the code for the function:
int gcd(int a, int b){
return b==0 ? a : gcd(b, a%b);
}
The unit tests are there to check if function was implemented correctly.
In the future they will help to debug the code.
Variables
Initialize variables immediately when they are defined .
Define all variables at the beginning of every function:
int someFunction(){
int i=0, j=0;
string result=Constants.NO_RESULT;
..................................
}
Keep it Modular
Make sure functions are small in size and have a clearly defined purpose.
Don't use more than 2 nested statements:
for(...){
if(...){
for(...){
// BAD BAD BAD
}
}
}
for(...){
if(...){
doStuff(params);
}
}
void doStuff(Object params){
// GOOD GOOD GOOD
}
Debug Progressively
Don't write the whole code at once. Debug when each module is completed.
Reuse the Code
Do not define a new function when another performing similarly exists.
Two people may be considered close if distance between them is less than 10 meters:
boolean areClose(Point a, Point b){
if(a.distanceTo(b) < 10){ // meters
return true;
}
return false;
}
Two cities may be considered close if distance between them is less than 100 kilometers:
boolean areClose2(Point a, Point b){
if(a.distanceTo(b) < 100000){ // meters
return true;
}
return false;
}
Bad! Take out hard-coded values first:
Constants.PEOPLE_DISTANCE = 10; // meters
Constants.CITY_DISTANCE = 100000; // meters
Then add an extra parameter to the function as such:
boolean areClose(Point a, Point b, int distanceThreshold){
if(a.distanceTo(b) < distanceThreshold){ // meters
return true;
}
return false;
}
And call using the needed threshold:
Point a=new Point(67.4352, 26.1345);
Point b=new Point(67.2342, 25.6545);
areClose(a, b, Constants.PEOPLE_DISTANCE); // false
areClose(a, b, Constants.CITY_DISTANCE); // true
Indent the Code
Make sure the code is properly indented.
Not like this:
ArrayList
points=new ArrayList();
BufferedReader bufferedReader=new BufferedReader(new FileReader(filePath));
String line=bufferedReader.readLine();
while(line!=null)
{
// using more indentation so I see it easy later!
points.add(new Point(line));
line = bufferedReader.readLine();
}
Route route=new Route(points);
If some code has bad indentation, formatters exist online (ex:
PHP formatter).
Make it Portable
Never have hard-coded variables. It becomes difficult to move the project somewhere else.
Agree to a naming Convention
It is very hard to analyze code written with different naming conventions.