Project Creation Tips

Tue, 2 Nov 2010

Over the past few years I've learned a lot, mainly from mistakes. I think that's a great way to learn. These are a few things I've learned that seem to be pretty important, because when they linger I dislike working on any project. So here are a few Project Creation Tips.

#1 Organization

I think this is the most important thing. Anytime you work with a bunch of code, if things aren't organized it's going to turn into one big search nightmare to make small changes. Organization will also keep you consistent with other projects.

Folders and files should be easily identifiable. If you are building a website It's standard practice to have a header, a footer, and a main page called index. Don't call them: top, bottom, main. That's confusing and most people don't do that. If you use a sidebar, rather than call it left or right, just call it sidebar so you won't have to rename it later if you change it's position.

#2 Folder Happy

I find too many folders are a dread to work with, and I learned this later on. Especially too many nested folders. I have an application with this layout to get to the cache: ~/system/application/views/__cache/. Now that's not too terrible in my opinion, especially since I rarely need to access the folder. It's still digging into 4 folders though! Whenever I nest this much I wish I didn't.

#3 Naming Convention

Nothing drives me more nuts than names that don't keep consistency. If there is a folder of classes, they should all be named the same, for example: MyItem.class.php, Other.class.php, if there were something.php in that same folder, it's inconsistent and doesn't logically make sense why it's there. It should be called Something.class.php, the casing should also match.

#4 Code Convention

Much like the above, when digging through code I sometimes see: $strVar, $sVar, $var. And it looks like either many people worked on this or the person couldn't make up their mind in naming their variables! I think in PHP it's a good idea to follow the Zend Code Conventions as much as possible, because they are somewhat standard and attractive.

If you are working with CSS, rather than having #element-name, #otherItem, #another_item, you should stick to the same style of naming things. What would be better is sticking to one way of doing in, my personal prefence is camelCase so it'd turn out like: #elementName, #otherItem, #anotherItem, #moreWordsHere

And whenever possible, be descriptive! I remember looking back at code that had a variable I called $strValue, I had no idea what it did and i had to look around. If it were named $nameOfUser then I'd stop wasting a lot of time skimming code! :P

#5 Misuse of Syntax

I was recently going through some PHP by someone, and although they were good with a lot of the built in string functions, they really lacked in making something easy to work on. There are a while loop like this:

while (true) {
	$p .= "Text here with a line\n";
	$p .= "More text here.\n";
	$p .= "Some more.\n";
	// And on for about 100 lines.
}
echo $p;

Now that is just ridiculous! They should have just used a HEREDOC, NOWDOC, or a bunch of lines with one variable. I think it's okay to build on a string when it's not very big, but not for that long.

#6 Pre-Planning

This could be higher up on the list. But without a good plan and how to map out the flow of the system, a lot can go wrong. When you eventually put months of time into code and realize you have a flaw in the order of operations, a lot might have to be changed and that's going to hurt motivation -- because building is much more enjoyable than fixing flaws.

Conclusion

These tips aren't anything new, the point is to keep a reminder circulating the web to make programmers live's easier. I think much of this has to be learned by trial and error and seeing how dreadful a project you once loved can become the bane of your existence. And by following such guidelines your view of your application will be much better.