I have been programming from last 8+ years. I worked on different platforms and languages. Every language has its own power and beauty. But there are some global standards (or principles) which if followed could increase the ease of maintenance and scalability of code. Also, these standards greatly help in environments where multiple people are working on same project.
Another plus point for such code is that if a developer leaves, then a new developer could very easily follow and start from where he left due to good readability and clear code. In this regard a very good read is Code Complete by Steve McConnell. I follow a few rules taken from Code Complete, other sources and my experience:
Naming Conventions:
Variable names should be in all lower-case, with words separated by an underscore, example:
|
1 2 3 4 5 |
//Incorrect $currentuser $currentUser //Correct $current_user |
Names should be descriptive, but concise. We don’t want huge sentences as our variable names, but typing an extra couple of characters is always better than wondering what exactly a certain variable is for.
Function Names:
Functions should be named descriptively. Function names should preferably have a verb in them somewhere.
Function Arguments:
Arguments should be treated same as variable names. In most cases, we’d like to be able to tell how to use a function by just looking at its declaration. And also when we generate documentation via script, these will help us understand it better.
Include the braces:
One should use complete syntax for conditional / loop structures. Even if the body of some construct is only one line long, do not drop the braces. Examples:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
//Incorrect if (condition) do_stuff(); if (condition) do_stuff(); while (condition) do_stuff(); for ($i = 0; $i < size; $i++) do_stuff($i) //correct if (condition) { do_stuff(); } while (condition) { do_stuff(); } for ($i = 0; $i < size; $i++) { do_stuff(); } |
Comments:
Each function should be preceded by a comment that tells a programmer everything they need to know to use that function.
The meaning of every parameter, the expected input, and the output are required as a minimal comment. The function’s behaviour in error conditions (and what those error conditions are) should also be present. Nobody should have to look at the actual source of a function in order to be able to call it with confidence in their own code.
Especially important to document are any assumptions your code makes, or preconditions for its proper operation. Any one of the developers should be able to look at any part of the application and figure out what’s going on in a reasonable amount of time.
