As long as we develop software as a team (with team members), it's very important to write clean code so that the other members can read and enhance. As we know, global coding conventions are defined depending on programming languages but we should follow very basic and simple rules NOT depending on programming languages to make it clean.
Here's the principle of coding conventions in our company and I hope it would help your development team.
Line length
120 characters is the maximum.We recognize that this rule is controversial, but so much existing code already adheres to it, and we feel that consistency is important.
Exception: if a comment line contains an example command or a literal URL longer than 80 characters, that line may be longer than 80 characters for ease of cut and paste.
Write short functions
50 lines is the maximum.Prefer small and focused functions.
We recognize that long functions are sometimes appropriate, so no hard limit is placed on functions length. If a function exceeds about 50 lines, think about whether it can be broken up without harming the structure of the program.
Even if your long function works perfectly now, someone modifying it in a few months may add new behavior. This could result in bugs that are hard to find. Keeping your functions short and simple makes it easier for other people to read and modify your code.
You could find long and complicated functions when working with some code. Do not be intimidated by modifying existing code: if working with such a function proves to be difficult, you find that errors are hard to debug, or you want to use a piece of it in several different contexts, consider breaking up the function into smaller and more manageable pieces.
Nest depth
3 nest depth is the maximum.We recognize that we often need deep nest but we should structure with smaller
functions in this case.
Deep nest can be big reasons of unreadable code.
Good example of PHP (nest depth is 2)
if($flag === true) {
foreach($key as $val) {
doSomething($val)
}
}
Bad example of PHP (nest depth is 4)
if($flag === true) {
foreach($key as $val) {
switch($key) {
case 1:
if($weather === 'cold') {
wearCloth();
goBackHome();
} else {
takeOffCloth();
goToBeach();
}
break;
case 2:
if($weather === 'cold') {
turnOnStove();
readBooks();
} else {
turnOnAC();
eatIceCream();
}
}
}
}
Magic number
DO NOT USE magic number.Magic number is plain numeric character on source code and it also cause unreadable code.
Exception: You can write 0 or 1. Because we sometimes need to use these number without concrete meaning. Of course, you should define as constant if you can define them.
Good example of PHP
switch($statusCode) {
case OK:
setValue(KYE_OF_SUMMER);
break;
case MOVE_TEMPORARILY:
setValue(KYE_OF_SPRING);
break;
case NOT_FOUND:
setValue(KYE_OF_WINTER);
break;
}
Bad example of PHP
switch($statusCode) {
case 200:
setValue(33);
break;
case 302:
setValue(35);
break;
case 404:
setValue(38);
break;
}
General naming rule
Function names, variable names, and filenames should be descriptive; eschew abbreviation.Give as descriptive a name as possible, within reason. Do not worry about saving horizontal space as it is far more important to make your code immediately understandable by a new reader. Do not use abbreviations that are ambiguous or unfamiliar to readers outside your project, and do not abbreviate by deleting letters within a word.
Good example of PHP
$priceCountReader; // No abbreviation. $numErrors; // "num" is a widespread convention. $numDnsConnections; // Most people know what "DNS" stands for. $i // General variable name to express the number of count within only loop.
Bad example of PHP
$n; // Meaningless. $nerr; // Ambiguous abbreviation. $nCompConns; // Ambiguous abbreviation. $wgcConnections; // Only your group knows what this stands for. $pcReader; // Lots of things can be abbreviated "pc". $cstmrId; // Deletes internal letters.
0 Comments:
Post a Comment