eZ Community » Forums » Discussions » Best practices - QA#3
expandshrink

Wednesday 03 April 2013 8:50:27 am - 4 replies

» Read full blog post

Introduction

In my previous post I talked about having a code formatting standard to make the code more readable. Having established this as a routine, the next step of readability is to consider how to make what you do with the code more readable. This part is rather hard to define, so I'm going to talk about some best practices here.

[QA#2 - Code formatting standards]

Wednesday 03 April 2013 10:41:00 am

Nice post!

While I generally agree with most of the recommendations given, I find myself often breaking some rules, in particular:

- too long function bodies

- too many params in method signatures

- too many methods in a class

- too many static methods

I put in fact those rules on a much lower scale in my own mental guidelines.

It seems that when developers focus too much on adhering blindly to them, they reduce the attention they give to making an architecture understandable (priority 1 in my own scale) and extendable (priority 2).

Otoh I have one rule which is extremely important: spend time to find good names to your classes, function names and functions parameters. Parameter names being much more important than their type is one of the main reasons coding in php is much more fun than coding in Java. In other words, if you can not communicate to a fellow coder the intention of code with function names, you do not have a clear mental picture of what it should do.

And some more:

- avoid putting all state in your objects, introducing a mandatory order in the calls to its methods and black-box magic behaviour - which is generally not documented; prefer passing state around explicitly in function parameters

- always have functions return something unless it really makes no sense

- always check and handle errors when they can happen (or use exceptions to make sure the errors are noticed by upper-level code). file writes can fail, http calls as well, etc... In fact it is hard to write any non trivial function which can not fail

As an example of code which tries to adhere to good-coding guidelines but fails in the overall scheme I would take the autoload config generator class. It separates its workings in many small methods, but still conflates together the generation of autoload config and the serialization and writing of it, making it very hard to e.g. get back the generated config as an array.

Modified on Wednesday 03 April 2013 10:44:16 am by Gaetano Giunta

Wednesday 03 April 2013 1:58:26 pm

Thanks, Gaetano.

Yes, I also keep writing too long functions in particular. But I'm working on fixing that. happy.gif Emoticon

I would say that an architecture should become more understandable with shorter functions, depending on how you implement them ofcourse. But I agree we should never follow such a list blindly, they are only ment as lose guidelines/warning signs. And keep in mind what I mentioned at the beginning of the post about different best practices conflicting with each other.

Thursday 04 April 2013 5:25:35 pm

Great points. Another good measure of function complexity is cyclomatic complexity. In other words, how many paths are there through this function, including returns, thrown exceptions, etc.? If you're trying to get proper test coverage, high cyclomatic complexity makes it difficult (8 paths through the code mean 8 tests are needed to hit everything), so it's better to write small functions that focus on more atomic tasks.

PHPMD is a nice complement to PHP_CodeSniffer, and can help identify some of the things discussed here. It's supported by PHPStorm for use on the desktop, and can be easy added to a build process as well.

Friday 05 April 2013 8:20:12 am

Thank you, Joe.

It looks like cyclomatic complexity should definitely have been a part of my article. I'll read more about this. happy.gif Emoticon

expandshrink

You must be logged in to post messages in this topic!

36 542 Users on board!

Forums menu

Proudly Developed with from