Is there a naming convention or maybe some guideline on how to name function parameters?
Since forever, I have been doing it like this:
function divide( $pDividend, $pDivisor )
{ ... }
That way I'll always know which variables were passed as parameters.
(This one's PHP, but it should be applicable to most programming languages)
Is there one major reason against this?
Is there a better way to do this or is it probably best to just avoid such naming schemes?
If :
your functions/methods are well written and short (as they should be)
the variable names are descriptive enough
This practice is not needed.
If you need this, it means that the code written is not readable enough (functions/methods too long), cryptic variable/function names, bad OO practices, shortcuts, code debts, etc. :)
So it would be a signal that the code needs to be refactored/improved.
I think taking the advice of Code Complete regarding naming -anything- would be justified it's whole chapter 11 is on naming variables properly):
Don't name it j, k, i, m, n (unless it's just for an iteration) or "placeholder" or "test". When the "test" works, I often don't take the time to rename the variable wherever it's been listed.
Call it a descriptive name that's separate from the code's function ie "EmployeeComments" not "XMLEmp_Comment_File" because a lot of that information (XML, external file) could change, but that the program's working with "Employee Comments" won't
Keep it as broad and human readable as possible so you're coding in English (or your language) not $j=$k/sqrt($pi); or something equally unintelligible.
As for parameters specifically, I've never used the P notation. I like the idea, but if you named them right wouldn't it be clear they were the parameters for the function?
I've heard that some people will keep their function parameters one style, with the type of data a the first part of the variable (array = arr), and then capitalize the following words:
$arrFormData
where the rest of their variables are in a different style, where the words are all lower case, no type definition, and the words are separated by underscores.
$form_data
Personally, I tend to keep my variables the same as the rest of my variables, purely because on the first two lines of a function, I'm making sure that they are what I expect, or throwing an exception. After that, there shouldn't really be a difference between local variables and variables passed in. But, if it keeps your code clearer to type it one way, by all means.
You should follow general guidelines for how to name parameters as you would for other variables (names should be clear, accurate, specific, consistent, and usually 8-20 characters long).
As for the prefix, I would recommend the opposite: leave the parameter unmarked, and mark anything that you do with the parameter in the function as a separate variable. For example:
function upperCase($title) {
$upTitle = ucfirst($title);
return $upTitle;
}
In my example, I use a bare parameter, $title. After I transform the input, I call it something else to indicate that it is now in a transformed state, $upTitle. That way I know that it is no longer just the function parameter. Merely calling your parameter $pTitle does not give you quite the same advantage as this consistent approach.
If you think about it, your method marks all the parameters on the interface, which is not the best level. If you look at the API of your program, all your function parameters are marked with $p meaning parameter, which is redundant. You are saying, all of my parameters are parameters, which we already know since they are part of the API. So I would recommend dropping the prefix for the parameter and instead using a series of semantic prefixes that denote what you have done to the parameter to transform it within the function, as in my example.
I disagree with the previous suggestion that you should just make your code more clear. Having clear code does not remove the need for having clear naming conventions.
I have naming conventions for some variables, like member fields or static fields, because the declaration of the variable may be far away from the code where I use it. For parameters or local variables I do not use anything, as usually the variable definition is about ten lines away.
Especially in the all IDE camp people seem to get more and more to dislike any prefix or suffix, as "the IDE provides highlighting". Well, it doesn't help me, and I dislike having semantic information only available as color. However, I can see there point, as the variable name should make the most important information clear, and if it doesn't, nothing helps.
So, this is more about style. Good naming is more important than good prefixes. For the schemes: pick one, stick to it. This will help the poor maintenance developer. Yes, those are the people who usually also prefer { } around single statement blocks and so on, but it helps.
The greatest chance for confusion for me is in member functions. If possible, I like to see differences in naming between:
local variables: index
class member variables: m_index
class static variables: ClassIndex
global variables: INDEX
This can make it easier to track down what's happening where. However, I agree with Toto that it's best to make your functions short enough so that these conventions don't make or break your ability to figure out what's going on.
You can follow the PHP Coding Standards or Coding standard for php which is suggested to contribute in core php.
So after looking at all this, I decided to go with:
ClassName
methodName
propertyName
function_name (meant for global functions)
$variable_name
There are many ways to name variables (as you can see from the answers)
But as a general rule, they should be named such, that it is clear from just looking at the variable itself, what it does and what it is used for, right there and not have to go through thousands of lines of code to find out - and not just for who else might have to troubleshoot later but if your code is thousands of lines long for your own good if you yourself have to troubleshoot later
AND WHATEVER NAMING CONVENTIONS YOU CHOOSE BE CONSISTENT THROUGHOUT YOUR CODE - this cannot be iterated enough :)
Personally I use the following:
first part of the variable is for what it is
second part is for what it does/is used for
and for variables needed outside the function, class, etc. the third part is for the function, class, etc. it comes from
Ex:
I want to name the variable for a video thumbnail on the front page:
so i start with what it is (lower_case) - thumbnail
then I add on what it is used for (first letter upper_case) - Video
and since I need it on the front page outside the function I finish off with the function it came from (seperated by under_score) - getVideoAll
Giving me $thumbnailVideo_getVideoAll
That way no matter where I look at the variable in any part of the code (HTML, PHP, etc.) I know...
ah this is the thumbnail for the video I'm trying to show and if it for some reason doesn't work I firstly don't need to go anywhere to spell-check and secondly I know exactly what function, class it was called for (getVideoAll) and can just go there to troubleshoot
If I instead just had named it $tnVid I might personally have a vague notion of what it is but someone else looking at will have no idea that tn stands for (t)humb(n)ail, etc.
so to troubleshoot they would have to first look at the surrounding code to maybe infer that it is probable a variable for a thumbnail and second go through thousands of lines of code to find what function, class, etc. it came from - and that's hours of work just finding what you need to even start troubleshooting - instead of the 5 seconds it takes seeing $thumbnailVideo_getVideoAll and going -
ah this is the thumbnail for the video and I need to go to the function getVideoAll to troubleshoot
Related
Introduction
I have some sort of values that I might want to access several times each page is loaded. I can take two different approaches for accessing them but I'm not sure which one is 'better'. Three already implemented examples are several options for the Language, URI and displaying text that I describe here:
Language
Right now it is configured in this way: lang() is a function that returns different values depending on the argument.
Example: lang("full") prints the current language, "English", while lang() prints the abbreviation of the current language, "en". There are many more options, like lang("select"), lang("selectact"), etc that print different things. The code is too long and irrelevant for the case so if anyone wants it just ask for it.
Url
The $Url array also returns different values depending on the request. The whole array is fully defined in the beginning of the page and used to get shorter but accurate links of the current page.
Example: echo $Url['full'] would print "http://mypage.org/path/to/file.php?page=1" and echo $Url['file'] would print "file.php". It's useful for action="" within the forms and many other things. There are more values for $Url['folder'], $Url['file'], etc. Same thing about the code, if wanted, just request it.
Text
[You can skip this section]
There's another array called $Text that is defined in the same way than $Url. The whole array is defined at the beginning, making a mysql call and defining all $Text[$i] for current page with a while loop. I'm not sure if this is more efficient than multiple calls for a single mysql cell.
Example: echo $Text['54'] prints "This is just a test array!" which this could perfectly be implemented with a function like text(54).
Question
With the 3 examples you can see that I use different methods to do almost the same function (no pun intended), but I'm not sure which one should become the standard one for my code. I could create a function called url() and other called text() to output what I want. I think that working with functions in those cases is better, but I'm not sure why. So I'd really appreciate your opinions and advice.
Should I mix arrays and functions in the way I described or should I just use funcions?
Please, base your answer in this:
The source needs to be readable and reusable by other developers
Resource consumption (processing, time and memory).
The shorter the code the better.
The more you explain the reasons the better.
Thank you
PS, now I know the differences between $Url and $Uri.
It sounds like you're implementing ambiguous functions through the array notation. Normally, these would be classes with methods. $url['full'] would be $url->getFullPath(). Methods are preferred over the array accessor because methods are documented, and can be introspected by IDEs. Objects are more preferable because (in your examples) you can lazy-load the information. Right now, your script is compiling the $Url array and figuring out values for every possible key so it can be used in the script. Whereas a $request object could only do the parsing upon request - not instantiation.
I am using something like config array var. Where strings are set. Is better for later reading to use $LBL["hello"]='Hi!' than lbl(5). Think about yourself when you will return to your code aftre one year :)
Well, I read in my handy PHP book that it's very important to be able to distinguish between reference and variable parameters. The book says that the original value of parameterized variables are preserved when the variable is changed, and the original values of parameterized references change when the reference is changed. It says that's the key difference, if I am reading right.
Well, I'm wondering when each is more useful than the other. How do I know when to use variables and when to use references when I create my own functions?
It's pretty straightforward. Use references when you need to modify the value of the variable passed in to the function. Use variables when you don't need to or want to modify the value.
So, for example, if you're writing a function that takes an array and changes that array, you'd be better off using a reference for that array rather than returning a new array from the function.
"References" (variable aliases) make your code harder to understand and could be a source of hard to follow errors. There are no valid reasons to use references in php and to be on the safer side try to avoid them altogether.
And no, objects in php5 have nothing to do with "references".
"References" as implemented in php is a strange concept. Normally, in programming languages variables are independent of each other so that changing one variable doesn't affect others. Php "references" allow several variables to share the same value and to be dependent of each other. Basically, you change one variable, and suddenly another one, which you think is totally unrelated, is getting changed too. It's no good thing and often leads to much confusion.
Objects in php (do I need to add 'five'?) have nothing to do with "references" in the above sense. They behave much like C pointers (actually, this is what they are under the hood) - when you pass an object to a function, you actually pass a pointer, and the function can use this pointer to manipulate the object contents, but there's no way for the function to change the passed variable itself, for example, make it point to another object.
This "objects are references" misunderstanding is probably because people confuse php "references" (ampersand syntax) with the generic CS term , which also applies to pointers, handles etc.
You need two functions:
1. Retrieves plain text from a DB.
2. Based on 1, retrieves rich text - with new lines, font styles etc.
You expect function 2 to be much more used than function 1.
Would you name 1 text() and 2 - rich_text() or would you use the simpler text() for the name of 2, since it's expected to be more popular and use something like plain_text() for 1?
The more general question would be - do you consider function's expected "popularity" when naming it?
No, I don't consider a function's popularity. It's best to have descriptive names for both functions (e.g. one is plain_text() and one is rich_text()).
I think that it's best to use relatively specific names for all functions, since using more general names 1.) doesn't give the user too much of an idea of what the function does by reading the name and 2.) can lead to confusion.
Of course, how you name your functions is your choice: I just recommend that you give them somewhat descriptive names and that you name them (and order the arguments) consistently.
I hate nothing more than programming with an API where every function name is short and cryptic (PHP's string functions are that way, even though I'm used to it now -- strstr and strtok are hardly intuitive names for what they do).
It's worth thinking about popularity, sometimes, if the code is going to be very widely used. Common words in natural languages tend to be short.
Unless you think you're writing the next UNIX, however, you're probably better off to make the names descriptive and not worry about length.
I'd go for getPlainText() and getRichText().
As a rule of thumb, I always name my functions loosely based on what they do. If I was in your shoes, I would name function one retrieve_plain_text() and function two retrieve_rich_text(). I can now glance at either function name and immediately have a basic understanding of what the function is supposed to do: Retrieve (get from something, in this case the database) plain/rich (the type) text.
I prefer coding standards to be logical. This is my argument for why the following set of standards are not.
I need to know one of two things: (1) why I'm wrong, or (2) how to convince my team to change them.
camelCase: Functions, class names, methods, and variables must be camelCase.
Makes it hard to differentiate between variables and classes
Goes against PHP's lowercase/underscored variables/functions and UpperCamelCase classes
Example:
$customerServiceBillingInstance = new customerServiceBillingInstance(); // theirs
$customer_service_billing_instance = new CustomerServiceBillingInstance();
Functions/methods must always return a value (and returned values must always be stored).
This appears on hundreds of our php pages:
$equipmentList = new equipmentList();
$success = $equipmentList->loadFromDatabase(true, '');
$success = $equipmentList->setCustomerList();
$success = $equipmentList->setServerList();
$success = $equipmentList->setObjectList();
$success = $equipmentList->setOwnerList();
$success = $equipmentList->setAccessList();
The return value is rarely used but always stored. It encourages the use of copy-and-paste.
No static methods
Lines like the following appear thousands of times in the codebase:
$equipmentList = new equipmentList();
$success = $equipmentList->loadFromDatabase();
I would prefer:
$equipmentList = equipmentList::load();
What reason is there to not use static methods or properties? Aren't static methods responsible for non-instance-specific logic? Like initializing or populating a new instance?
Your code is not OOP unless everything returns an object
There's a piece of code that performs a query, checks it several ways for errors, and then processes the resulting array. It is repeated (copied+pasted) several times, so I put it in the base class. Then I was told returning an array is not OOP.
How do you defend these practices? I really do need to know. I feel like I'm taking crazy pills.
If you can't defend them, how do you convince the adamant author they need to be changed?
I would suggest trying to list down the goals of your coding standards, and weigh them down depending on which goals is the most important and which goals are less important.
PS: I don't speak PHP, so some of these arguments may contain blatantly incorrect PHP code.
camelCase: Functions, class names, methods, and variables must be camelCase.
Workplace's Apparent Reason: "consistency" at the cost of "information density in name".
Argument:
1) Since 'new' keyword should always be followed by a class, then you can easily spot illegal instantiation, e.g.:
$value = new functionName();
$value = new local_variable();
$value = new GLOBAL_VARIABLE();
would raise an alarm, because 'new' should be followed by a TitleCase name.
$value = new MyClass(); // correct
Relying on Case makes it easy to spot these errors.
3) Only functions can be called, you can never call variables. By relying on Case Rule, then we can easily spot fishy function calls like:
$value = $inst->ClassName();
$value = $inst->instance_variable();
$value = $GLOBAL_VARIABLE();
3) Assigning to a function name and global variables is a huge deal, since they often lead to behavior that is difficult to follow. That's why any statement that looks like:
$GLOBAL = $value;
$someFunction = $anotherFunction;
should be heavily scrutinized. Using Case Rule, it is easy to spot these potential problem lines.
While the exact Case Rule may vary, it is a good idea to have different Case Rule for each different type of names.
Functions/methods must always return a value (and returned values must always be stored).
Workplace's Apparent Reason: apparently another rule born out of blind consistency. The advantage is that every line of code that isn't a flow control (e.g. looping, conditionals) is an assignment.
Argument:
1) Mandatory assignment makes unnecessary long lines, which harms readability since it increases the amount of irrelevant information on screen.
2) Code is slightly slower as every function call will involve two unnecessary operation: value return and assignment.
Better Convention:
Learn from functional programming paradigm. Make a distinction between "subroutine" and "functions". A subroutine does all of its works by side-effect and does not return a value, and therefore its return value never need to be stored anywhere (subroutine should not return error code; use exception if it is really necessary). A function must not have any side-effect, and therefore its return value must be used immediately (either for further calculations or stored somewhere). By having side-effect free function policy, it is a waste of processor cycle to call a function and ignoring its return value; and the line can therefore be removed.
So, there is three type of correct calls:
mySubroutine(arg); // subroutine, no need to check return value
$v = myFunction(arg); // return value is stored
if (myFunction(arg)) { ... } // return value used immediately
you should never have, for example:
$v = mySubroutine(arg); // subroutine should never have a return value!
myFunction(arg); // there is no point calling side-effect free function and ignoring its return value
and they should raise warning. You can even create a naming rule to differentiate between subroutine and functions to make it even easier to spot these errors.
Specifically disallow having a "functiroutine" monster that have both a side-effect and return value.
No static methods
Workplace Apparent Reason: probably someone read somewhere that static is evil, and followed blindly without really doing any critical evaluation of its advantages and disadvantages
Better Convention:
Static methods should be stateless (no modifying global state). Static methods should be a function, not subroutine since it is easier to test a side-effect-free function than to test the side-effects of a subroutine. Static method should be small (~4 lines max) and should be self-contained (i.e. should not call too many other static methods too deeply). Most static methods should live in the Utility class; notable exceptions to this is Class Factories. Exceptions to this convention is allowed, but should be heavily scrutinized beforehand.
Your code is not OOP unless everything returns an object
Workplace Apparent Reason: flawed understanding of what is OOP.
Argument:
Fundamental datatypes is conceptually also an object even if a language's fundamental datatype doesn't inherit from their Object class.
If you can't defend them, how do you
convince the adamant author they need
to be changed?
By giving strong/valid arguments! Still I think you should only change them when your arguments are really strong! Because most of the programmers at work are used to these coding standards which is a big point why to use them.
==
Like others told before this is pretty subjective, but these are mine opinions/arguments.
1. camelCase: Functions, class names, methods, and variables must be camelCase.
I would use the PHP style if I code in PHP and the Camelcase style if I code in Java. But it does not matter which style you choose as long as you stay consistent.
2. Functions/methods must always return a value (and returned values must always be stored).
This is nonsense in my opinion. In almost all programming languages you have some sort of 'void' type. But from a testing point of view most of the times it is useful if your function are side effect free. I don't agree that your production code should always use the return value especially if it does not have any use.
3. No static methods
I would advice you to read static methods are death to testability from misko
During the instantiation I wire the
dependencies with mocks/friendlies
which replace the real dependencies.
With procedural programing there is
nothing to “wire” since there are no
objects, the code and data are
separate.
Although PHP is a dynamic language so it is not really a big problem. Still the latest PHP does support typing so that I still think most of times static methods are bad.
4. Your code is not OOP unless everything returns an object
I believe(not 100% sure) a truly OOP language should do this(return an object), but I don't agree with this like a of like languages like for example Java(which I believe is not trully OOP). A lot of the times your methods should just return primitives like String/Int/Array/etc. When you are copying and pasting a lot of code it should be a sign that something is not totally right with your design. You should refactor it(but first have a tests(TDD) ready so that you don't break any code).
Many of these coding standards are very subjective, but some important things to consider are:
Get a single set of code naming and style rules, and follow them. If you don't have already defined rules, make sure to get rules figured out. Then work at refactoring the code to follow them. This is an important step in order to make it easier for new developers to jump on board, and keep the coding consistent among developers.
It takes time and effort to change the coding standards your company puts in place. Any change to the rules means that the code really has to be gone through again to update everything to be consistent with the new standards.
Keeping the above in mind, and looking more along the lines of specific PHP coding standards. The first thing to look at is if your company uses any sort of framework, look at the coding standards for that framework as you may want to stick with those in order to stay consistent across all the code. I have listed links to a couple of the popular PHP frameworks below:
Zend Framework Naming Conventions and Zend Framework Code Style
Pear Code Standards
My personal preference in regards to your specific coding styles:
1. camelCase: Functions, class names, methods, and variables must be camelCase
Class names should be Pascal Case (Upper Camel Case).
So in your example:
class CustomerServiceBillingInstance
{
// Your class code here
}
Variables and functions I generally feel should be camel case.
So either one of these, depending on your preference in terms of underscores:
$customerServiceBillingInstance = whatever;
$customer_service_billing_instance = whatever;
2. Functions/methods must always return a value (and returned values must always be stored).
This one seems like extra code and like you could end up using extra resources. If a function doesn't need to return anything, don't return anything. Likewise, if you do not care about what a function returns, don't store it. There is no point in using the extra memory to store something you are never going to look at.
An interesting thing you may want to try on this one, is running some benchmarks. See if it takes extra time to return something and store it even though you are not looking at it.
3. Your code is not OOP unless everything returns an object
In this instance, I feel you have to draw the line somewhere. Performance wise, it is faster for you to do:
return false;
Than to do:
return new Boolean(false); // This would use up unnecessary resources but not add very much to readability or maintainability in my opinion.
Defending a coding standard
To defend a coding standard that you feel is right (or showing why another is not as good), you really are going to have to bring up one of two points.
Performance. If you can show that a particular coding standard is adversely affecting performance, you may want to consider switching.
Maintainability/Readability. Your code should be easy to read/understand.
The goal is to find the happy median between performance and the maintainability/readability. Sometimes it is an easy decision because the most maintainable option is also the best performing, other times there is a harder choice to be made.
Standards and conventions exist for many reasons, but most of these reasons boil down to "they make code easier to write and maintain." Instead of asking "is this the correct way to do X?" just cut right to the chase and ask if this criterion is met. The last point in particular is simply a matter of definition. OOP is a means, not an end.
Many of those are matters of taste. You can argue for or against camelCase all day.
However, the storing of return values that are never used is Wrong. There is no value to the code. The code is not executed. You might as well sprinkle $foo = 47 * 3; around the code.
Any code that is not doing something useful must be removed.
The bigger issue is, if you're working for a clueless manager, it may be time to move.
The one aspect of this that I don't see anybody else commenting on is the "2. Functions/methods must always return a value (and returned values must always be stored)."
If you're not using exceptions, then any function that can fail does have to return a value. The last clause is misworded; return values don't always need to be STORED, but they do always need to be CHECKED. Again, that's IF you're not using exceptions, which isn't common these days, but it's still worth mentioning.
As far as I know quite a few of the conventions you posted are encouraged by the Zend PHP Framework as well. You're not alone, I'm a Codeigniter user and my work is pretty big on using Zend Framework. These kind of naming conventions are absolutely ridiculous and I honestly can only see an advantage of using camelCase for variable names, not function names as it makes things confusing.
Read this: http://framework.zend.com/manual/en/coding-standard.naming-conventions.html
Do these coding conventions look familiar to you?
Ok, really simple question - is it bad practice to use Variable functions in php?
I have a validator class that can use these and it makes sense to me but it does seem like it may be bad practice to do this?
EDIT: I can see that this there is going to be a lot of different opinions on this. Maybe if i explain how i intend to use them:
I have a base validator class with a method per field that i want to validate. I then have a classes that extend this base class and actually do the validating based on whatever logic i need. I have therfore called the methods in the base class after the fields they will validate. In the sub classes i can then simply loop through an array of required fields (whose keys match the field names also) and then simple call that function.
It seems really nice and clean but part of me keeps thinking its wrong.
EDIT: Where did those answers disapear to?
No, it's not bad practice. Variable functions exist for a reason. They are what other languages term callbacks, or function pointers; Used all the time for a variety of applications.
I can't judge your specific use case since you provide no code, but I don't think you can go very wrong here. At worst, you can degrade performance slightly with unnecessary function calls. At best, you're using them exactly as intended.