Best practices for a functions file?

Bonesnap

Hello all!

I have (what I consider to be) a relatively large project that I have been working on for over a year. In an effort to reduce coding and increase efficiency I created a functions.php file that I've been putting the code that is reuse a lot throughout the project into functions. The file contains fundamental aspects to the project (such as connecting to the database, printing the navigation menu, etc.) so it's included on pretty much every page in the site.

Due to the size of the project and the "scorched Earth" approach of the functions file, it has grown relatively large. With plenty more functionality planned for my project, the functions file is sitting at just over 1,300 lines and will definitely grow larger. My question is simple: what's the best practices for a functions file like this? At what point does its size start to compromise speed of the project?

According to Explorer, the file is 50KB. Should I be splitting this file into smaller chunks to reduce page loading times? I haven't noticed any noticeable delay and neither have my five testers. In terms of maintainability, it's not difficult for me at all since I've divided the file into sections via comments, and quite frankly it's much faster for me to hit ctrl-F than to find a specific file referring to a specific function. This is a personal project and I'm the only one working on it, so theoretically no one else should ever have to read my code.

But, with that said, should that time ever come, or if I want to show my code to a potential employer, etc. I'd like to know what I've done is considered the best approach. At what point should I be breaking up this file into smaller chunks, if at all? I suppose I could separate the database connection into another file.

Thank you for reading and any opinions would be greatly appreciated. 🙂

laserlight

For readability to ease maintenance, I suggest that you break up the file into logical sections, e.g., a file for database handling functions, another for menu generation functions, etc.

This may help very slightly if you only include the files where they are needed, though it will hurt very slightly in places where most of the files must be included anyway: but honestly the speed issue due to including the file(s) is minor compared to the gains you get from readability due to organisation, which in turn might help you make more significant improvements to the efficiency of the code itself.

Bonesnap

Darn, I was afraid you'd say that haha. I'm just going to find it incredibly tedious to go through all the pages and files of the project and figure out exactly which files will need to be included where.

I actually think it might hurt my maintainability since I can no longer simply hit "ctrl-f" and find the section of code I am looking for. Though I am thinking of consolidating my functions to make calling them simpler. For example, I have a function that retrieves a user name from an ID, but I also have a function that retrieves a user name from a thread title, so I rather consolidate them into a single function and have it perform differently based on the argument that it's passed, but will still have the same return type.

laserlight

Bonesnap wrote:
I actually think it might hurt my maintainability since I can no longer simply hit "ctrl-f" and find the section of code I am looking for.

So, it lowers your productivity for the time being because you will not be able to so easily use the tool that you are familiar with. There are other tools that allow you to search across files. One way it improves maintainability is that the structure of your code is implied by the files that the code is in, so someone looking through your code for the first time (or you yourself, for the first time in years) has a better sense of what is what.

Bonesnap wrote:
Though I am thinking of consolidating my functions to make calling them simpler. For example, I have a function that retrieves a user name from an ID, but I also have a function that retrieves a user name from a thread title, so I rather consolidate them into a single function and have it perform differently based on the argument that it's passed, but will still have the same return type.

Yes, that is feasible. Later, you may also want to consider if it makes sense to consolidate certain groups of functions that operate on the same data into a class.

NogDog

laserlight;10983390 wrote:
...
Yes, that is feasible. Later, you may also want to consider if it makes sense to consolidate certain groups of functions that operate on the same data into a class.

If you take this approach, you can combine it with the [man]autoload[/man] function to automatically load the needed classes as and where required. Even if you do not design full-blown objects, you could simply make a class of [man]static[/man] methods which you'd then call with the "::" operator:

function __autload($class)
{
   require $_SERVER['DOCUMENT_ROOT'].'/classes/'.$class.'.php';
}
$result = ClassName::fuctionName($arg);

Bonesnap

laserlight;10983390 wrote:
So, it lowers your productivity for the time being because you will not be able to so easily use the tool that you are familiar with. There are other tools that allow you to search across files. One way it improves maintainability is that the structure of your code is implied by the files that the code is in, so someone looking through your code for the first time (or you yourself, for the first time in years) has a better sense of what is what.

My only problem is that I hate change, but you do make an excellent point about organization. I was looking through my functions.php file earlier today and writing down all the function names. Just by scanning through them I think I can break them down into about 4-6 groups, which isn't too bad.

I'd also like to document my functions a little better and I think by moving them into separate files this will motivate me more to do so. Kind of a semi-related note... do you know of any IDEs that offer the ability to toggle on and off comments? I don't document my code enough (especailly functions) and I've discovered it's because I find comments to be incredibly distracting. I try to keep my functions pretty simple, but sometimes you cannot avoid a complicated or convoluted function, and I always tell myself, "I'll do it later", which, of course, never happens. 🙁

laserlight;10983390 wrote:
Yes, that is feasible. Later, you may also want to consider if it makes sense to consolidate certain groups of functions that operate on the same data into a class.

Hmm, never thought about that, but it seems like extra legwork for little if any payoff. But then I read...

NogDog;10983524 wrote:
If you take this approach, you can combine it with the [man]autoload[/man] function to automatically load the needed classes as and where required. Even if you do not design full-blown objects, you could simply make a class of [man]static[/man] methods which you'd then call with the "::" operator:
function __autload($class)
{
   require $_SERVER['DOCUMENT_ROOT'].'/classes/'.$class.'.php';
}
$result = ClassName::fuctionName($arg);

Relevant to my interests! That's a pretty nifty way of calling a function without having to write a bunch of includes/requires at the top of each file. I was planning on making a full list of my functions, their arguments and their return values for easy reference as I develop my project, and this will make it even more useful.

Thanks a lot for your input, guys! 🙂