How to determine code quality in PHP

[DerelictMan]

Off Topic:

Enough point scoring already

If you're referring to me, I apologize. Something came up while I was in the middle of composing my last response, and I didn't realize when I hit submit that someone else had already said basically the same thing that I did. I wasn't trying to score points...

If you didn't mean that, then ignore this.

[jayboots]

I suppose that we can keep enumerating technicalities, which are good practice, but doesn't ensure anything in and by itself. The real answer isn't a technical one though - it's the same as to "What makes a good novel". Good code has good litterary qualities.

As a programmer I often feel a bit misunderstood by my non-computer friends (I have a few left, yes). The general assumption is that programming is an engineering discipline - we all know the metaphore of 1's and 0's. Of course to some extend it is, but I have always felt that programming is much more of a linguistic discipline than a technical one. I failed math horribly in highschool, yet I make a good programmer (should I say it myself at least).

Eh? That sounds a little bit like a cop-out to me. I suspect that if you are indeed a good coder that you are probably much better at math than your high-school grades have lead you to believe. Programming is math just as math is language; however, neither are quite the same as natural human language. Without getting too philospophical, lets call math and code "artificial language" and note that they have been shown to be decidedly constrained in terms of what statements they can make (godel); to some extent, this is also true of natural language (wittgenstein) although we know statements can be made in natural languages that artificial languages can not represent. That said, if you are musing whether one can use similar constructs in both natural and artificial languages to make comprehension (flow or what have you) easier, then I'd agree that there is something to that. Still, I personally think that if the goal is to recogonize beautiful code, then you are perhaps better serverd by the ability to recogonize a beautiful equation rather than the ability to recogonize a good piece of prose.

So what is a good equation? Well, for one, they tend to express something complicated in a concise and often simple way (if you are versed in the terminology) and they often open up new avenues of thought (ie: make other statements possible). Yet one can draw definitions like that up until the cows come home. You can't really define it just as you can't really define what makes a good piece of art (yet when we go to the museum we can readily appreciate what is there). TAOP is the closest thing I know to a work that can even begin to shed light on the matter of good code and yet despite all its volumes and the precious wisdoms it distills, it can really only impart the feeling of the beauty that can be code. (yes, there are other great works too)

It occurs to me there are plenty of "ugly code sites" on the net. Maybe a museum of beautiful code is what is really needed. IOW, instead of looking always at the bad, we should also look at the good. At least then we can admire and be inspired even if we can't quite exactly say why or how.


best,

[McGruff]

What makes good code?

Good tests. And the simplest thing to make them pass.

[lastcraft]

Hi...

Good tests. And the simplest thing to make them pass.

So what is "simplest"?

Whilst I think TDD does a lot to sort out the mechanics, and the tight cycle is a great learning tool, I don't think it's enough. Once your tests pass, you still have to refactor. I don't think "remove duplication" is enough in itself either. Deciding if code is really common can be a rather subtle problem.

I can see why Martin Fowler went for the "worst practice" list (code smells) in the refactoring book. It's the same ontology as a military campaign or firefighting. There is no correct way to win a battle or fight a fire, but there are well known stupid things you can do.

So what makes the stupid things stupid?

yours, Marcus

[Selkirk]

Stupid things are stupid because they make the program harder to change, harder to understand and harder to get right.

[nacho]

What makes good code?

Readability
Maintainability
Reusability
Consistency
Robustness
Flexibility

I shall no doubt forget something, but I can tell you that if I see code that copes with all the above, I'm already a happy man.

[Galo]

Good code is like the perfect woman.
Hard to define, but it is love at first "site"

There is no perfect wo(man), .... nobody = perfect...

[dagfinn]

Programming is math just as math is language; however, neither are quite the same as natural human language.

Edsger Dijkstra had this to say about it in 1975 (http://www.cs.virginia.edu/~evans/cs...gs/ewd498.html):

Programming is one of the most difficult branches of applied mathematics; the poorer mathematicians had better remain pure mathematicians.

It occurs to me there are plenty of "ugly code sites" on the net. Maybe a museum of beautiful code is what is really needed. IOW, instead of looking always at the bad, we should also look at the good. At least then we can admire and be inspired even if we can't quite exactly say why or how.

You're ideas are similar to the thought process I went through before starting this thread. I started out from the question of how to find forum software that's not an "utter disgrace". So I thought, what I would like to have is a web site that with reviews and ratings of the code quality of available software packages.

That won't happen tomorrow, but at least we can discuss the prerequisites for a project like that. And it seemed to me that the most useful starting point would be to have some agreement on how to tell the difference between good and bad code.

[Etnu]

I would say catagorically untrue. Polymorphism is just as powerful in a dynamic language as a staticly typed one. Can you explain yourself further?

Dynamically typed languages don't need to be restricted from allowing certain data types to have actions performed on them. Polymorphism amounts to a (highly inflexible) whitelist of objects that a given action can be performed on. Duck typing (in all it's various incarnations, OO or not) is infinitely more powerful.

Polymorphism exists for the purpose of code reusability while retaining (the illusion of...) "type safety". Type safety is only truly important in languages where you're dealing with memory directly, anyway. Dynamically typed languages carry their type information around with them, so the big worries about type safety go out the window (you'll always have the correct size, always know what members are available, etc.)

If you want to argue the generic definition of polymorphism being the simple concept of reusing the same code on multiple pieces of data, I'd agree with the sentiment that it's useful, but in that case it has absolutely nothing to do with OOP since it's just as easy to write polymorphic procedural code as it is to write OO code, you just get the marginal benefit of being able to segment the code a little better (although in languages like php, even that's mostly a non-issue since you can go as far as putting implementations for different data types into different files, if you want).

What I argue as being a crutch is polymorphism in the atrocious whitelisting capacity that it exists in C++ and Java.

Before I show any examples, I want to point out that Ruby is the only dynamic language I know. I imagine other dynamic languages support duck-typing as well, but I'm not positive.

If they didn't, they'd be fairly hard to use, wouldn't you say? Unless you're not using them for much more than simple scripting (think bash), that is.

============================================

Now, this has gone entirely off-topic. My original point was that OO vs. procedural code has absolutely zero impact on the relative quality of any given piece of code. Quite simply, the benefits afforded by OO are almost universally offset by the increased complexity, and as such the majority of people don't get it right, and wind up producing lower quality code than they would had they simply used a clean procedural interface instead.

So what makes the stupid things stupid?

This one is almost universal in every discipline: doing too much to achieve a goal. Keep it Simple. The key to good writing is to be concise; never use 10 words to convey what you could in 3. The same can be said of programming.

Flexibility

Past experience has taught me that "flexibility" is almost always violating the "Keep it Simple" mantra. Don't make boneheaded limitations, but at the same time don't waste effort making something "flexible" when you're never going to need it to be. You'll probably re-write the whole damned system before you ever actually need your "flexibility".

Edsger Dijkstra had this to say about it in 1975 (http://www.cs.virginia.edu/~evans/c...ngs/ewd498.html):

he also said...

Besides a mathematical inclination, an exceptionally good mastery of one's native tongue is the most vital asset of a competent programmer.

Which just goes to show that arguing that something someone said a quarter century ago has absolutely no bearing on any current discussion. Appeal to authority is a textbook logical fallacy, you know.

[kyberfabrikken]

Eh? That sounds a little bit like a cop-out to me ... That said, if you are musing whether one can use similar constructs in both natural and artificial languages to make comprehension (flow or what have you) easier, then I'd agree that there is something to that. Still, I personally think that if the goal is to recogonize beautiful code, then you are perhaps better serverd by the ability to recogonize a beautiful equation rather than the ability to recogonize a good piece of prose.

Perhaps so - I didn't think long and hard before posting that, even if it could look that way. If you see math as a linguistic discipline, of course it doesn't oppose humanism. I suppose this was where I was getting at, when I was speaking from the (naive) perception of math as a "hard" science. I do suspect though, that the prosaic qualities are equally important in recognizing good code, as the syntactical.

It occurs to me there are plenty of "ugly code sites" on the net. Maybe a museum of beautiful code is what is really needed. IOW, instead of looking always at the bad, we should also look at the good. At least then we can admire and be inspired even if we can't quite exactly say why or how.

You're ideas are similar to the thought process I went through before starting this thread. I started out from the question of how to find forum software that's not an "utter disgrace". So I thought, what I would like to have is a web site that with reviews and ratings of the code quality of available software packages.

Ridiculing bad code may be entertaining, but is probably not very constructive. A site dedicated to exhibit excellent code could be an interesting alternative to the daily wtf. In a way - isn't this partly what the open source movement is all about ?

[kyberfabrikken]

Which just goes to show that arguing that something someone said a quarter century ago has absolutely no bearing on any current discussion. Appeal to authority is a textbook logical fallacy, you know.

I don't think he did. He was making a quote, which stands by it self. I think you did though, in taking another quote from the same text and using as an argument for the validity of the first. That said, I don't really see what's wrong with the second quote (the one you brought forth).

[DougBTX]

Duck typing (in all it's various incarnations, OO or not) is infinitely more powerful.

Polymorphism exists for the purpose of code reusability while retaining (the illusion of...) "type safety".

Wikipedia describes Python's duck typing as:

"Pythonic programming style that determines an object's type by inspection of its method or attribute signature rather than by explicit relationship to some type object ("If it looks like a duck and quacks like a duck, it must be a duck.") By emphasizing interfaces rather than specific types, well-designed code improves its flexibility by allowing polymorphic substitution."

Duck typing is a form of polymorphism, it isn't polymorphism vs duck typing because duck typing is polymorphism.

I think what you're really talking about is the distinction between explicit static interface declarations, and informal "it just works" dynamic duck typing.

In this case, you're perfectly right, declaring explicit interfaces isn't nearly as useful in dynamic languages as it is in static languages, because static languages don't compile without it.

In that vain, I'd say the first thing to look for in good code, is that it compiles/runs without error warnings

Douglas

[McGruff]

If you want to argue the generic definition of polymorphism being the simple concept of reusing the same code on multiple pieces of data, I'd agree with the sentiment that it's useful, but in that case it has absolutely nothing to do with OOP since it's just as easy to write polymorphic procedural code as it is to write OO code

Oh come on. In any version of php I've ever tried I can only have one function named "foo" at a time.

Polymorphism just means that a number of different types all implement the same interface. The type is irrelevant - that's the whole point. In OOP different types can be hidden behind a common interface. In procedural you're passing around data which isn't encapsulated by anything. You'll have to apply different functions to different types. Bang goes polymorphism.

My original point was that OO vs. procedural code has absolutely zero impact on the relative quality of any given piece of code. Quite simply, the benefits afforded by OO are almost universally offset by the increased complexity

I don't use OOP because it makes things more complicated. I use OOP because it makes things simpler. That "simple" procedural code is not as simple as it looks. Complexity still exists although it may not have been understood. OOP is a way to tame that, disentangling separate threads into cohesive objects.

[Selkirk]

Good code is like the perfect woman.
Hard to define, but it is love at first "site"

There is no perfect wo(man), .... nobody = perfect...

There is also no such thing as perfect code. We view the quality of code through the lens of the changes we have to make to it. First, we are asked to make a change to an unfamiliar code base. If the change is easy to make, we consider the code good. If the change is hard to make, the code is bad. For a different change, we might feel different about the same code.

Along the way, we can also imagine some potential changes. If the code would react well to potential changes we have in mind, we consider it good. If it wouldn't, we consider it bad.

We also consider standards and best practices. If the code conforms to these, we consider it good and if it doesn't we consider it bad. Since the more of these we know, the less likely that any given piece of code conforms, maybe the more you know the more everyone (else's) code is bad.

For the most part, these are subjective and situational measures.

[dagfinn]

Which just goes to show that arguing that something someone said a quarter century ago has absolutely no bearing on any current discussion. Appeal to authority is a textbook logical fallacy, you know.

Appealing to authority was not my intention. I just found the quote interesting.

EDIT: BTW, the phrase "textbook logical fallacy" could be mistaken for an appeal to authority.

[lastcraft]

Hi...

If the change is easy to make, we consider the code good. If the change is hard to make, the code is bad.

Except that there are always exceptions. For example, take the Ookles codebase. One of the aims of the core library is server farm scale. There is no ActiveRecord style ORM here. That makes certainly things harder to change. The code is tuned from the ground up to work with MySQL, so you cannot change that. It's not unit tested and, by Scott's own admission, buggy as hell. However, I think it's good programming .

You see it really identifies the problem it is trying to solve: a startup attempting a rapid breakthrough into a mass market. Ookles has some nice features, such as assuming a replication environment from the start. It assumes sessions and the like are on separate DBs, so it's a multiple connection environment (no Singleton connection objects). They know the GUI is going to change a lot, so they've given free reign to the AJAX guys and other wise kept out of the way. They keep most of the data as blobs (it's for data sharing on the net), and so don't need a flexible storage model. And so on. It's a clever solution, given the problem space.

Someone said that design and code quality were the same thing. Well, I say look at Ookles and face a contradiction. It's more subtle than that.

So maybe we need "good in a certain way" as a criteria. The design goals should sit right next to the solution. Both should be enscribed on the plaque in the good code museum.

yours, Marcus

[McGruff]

So what is "simplest"?

The obvious like one method is better than two, five lines better than ten. Not adding features which you think you might need later, maybe, but which aren't specifically needed for the problem at hand. Good code has to begin with real requirements which are clearly expressed. The actual code often feels like the easy bit.

As Selkirk said, one of the stupid things to do is to make things harder to change. I'd much rather have a less than perfect but fully tested app than a perfect one with no tests. The latter is a beautiful statue: I can't do anything with it. With tests, all the machinery is in place to knock it into shape - any shape. At any given moment it might be better or worse but fluidity is more important to code quality than some kind of static perfection. Both are good but first you've got to get through the rapids in one piece.

[Fenrir2]

I think it is impossible (or VERY hard, especially in impure languages) to prove that a certain piece of code that passes a unit test is in fact the shortest code possible.

The simplest solution is often the shortest (not counted in lines, but code elements), but not always.

Good code is the most straightforward solution for a problem. That doesn't involve objects often.

[33degrees]

And sometimes the most straightforward solution to a problem can still be very complex.

[Dr Livingston]

Good code is something which tells a story... In most cases this is the domain; If you can grab an understanding of the domain purely from the code and nothing more, then you are onto something, otherwise why bother?

[akrabat]

The definition of good code also depends on the problem the code is solving.

Personally I think good code is code that I can understand what it does and why it does it in that way. It gets bonus points for being easily modifiable to the new definition of the problem that the client has come up with!

[beetle]

The definition of good code also depends on the problem the code is solving.

I disagree. Something is either well implemented or not - with various levels of grey. Functionally, this is segregable from the problem being solved by that code..

At some point you can strip away all the application-specific baggage of a project and objectively analyze the implementation, which I believe is the crux of this discussion. I'm not saying the definition or even recognition "good code" is entirely unconditional, but you have to adopt a purist perspective at some point or you'll abstract your assessment into a much weaker critique than it should be.

[jayboots]

lastcraft brought up a good point: context is very important. This extends to several areas: "good code" in the case of a framework is different than "good code" in the case of a specific method which is different again than "good code" in the case of an industrial embedded application which is again different than "good code" for... well, the list goes on.

To make it clearer with an arbitrary example, a really elegant and optimized (and finalized!) search algorithm has different criteria for "good" than, say, an order processing pipeline executor that must meet changing business needs over-time.

We ought be careful when we say things like "good code is maliable", "good code is efficient", etc, because without context any of those sorts of statements can be correct or not.

[Fjoggen]

Good code is like the perfect woman.
Hard to define, but it is love at first "site"

There is no perfect wo(man), .... nobody = perfect...

I was trying to be funny, however you are absolutely right there are no items. ideas, or code that is perfect.

Altough my poor excuse of a joke wasn't as successfull as i thought it would be, it still describe what I wanted to express:
What we or rather you, since I haven't yet contributed, are trying to define is an idea that will differ from project to project and person to person. My idea of the "perfect" woman is probably not the same as yours, which of course is a good thing. Applied to the world of programming, "My idea" must be understood as one projects idea and as "jayboots" argued: Good code for one projects isn't automatically good code for another

Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.
~Antoine de Saint-Exupéry

In reality what Antoine de Saint-Exupéry is describing is the process of refactoring. However in the search of perfection I might float away from the ground named reality. Never the less by using that principle on the arguments used in this thread, I believe you have defined a few basic definitions which are language and project independent for good code:

• Readable - Well formated, and esthetically pleasing
• Commented - Describes a process which otherwise might cause confusion
• Understandable - The applications flow is easy to follow

Likewise there exists ideas that a newcomer to the world of programming might misunderstand as a mean to automatically transform their code into good code .

• Design patterns - One of many ways to solve a problem, but what if the problem is a result of bad code.
• OOP vs Prosedural, Java VS Fortran - It doesn't matter if you drive a Porsche or a Ferrari, you might still crash.

Shifting the focus back to my original joke; defining good code is like defining the perfect partner. We usually share a few fundamental common rules, it is what we wrap around those that separates us.

As a finally observation it is interesting to note the difference between the infamous(?) PHP forum software that isn't an utter disgrace? and this one. Notice how much easier it is to pinpoint and agree upon what bade code is.

Edit
Spelling, etc

[been]

I'd say the first thing to look for in good code, is that it compiles/runs without error warnings

Although this might be considered a trivial thing, I think it is a good starting point, as this relates to the most important external quality factor of a software system: Correctness.

By external quality factors, I mean desirable qualities of a software system that are visible to the client/constituent and the end users of that software system. These are the elements that will determine the amount of satisfaction experienced in using that system.

There are a bunch of those factors, what follows is a list of (imho) the most important ones:

- Correctness: This must be, without a doubt, the most important one; If a system doesn't do what it is specified to do, then it is of no use.
- Robustness: The agility of the system to react in an appropriate way to exceptional circumstances
- Extensibility: How easy the system can adapt to changes in the specifications
- Reusability: The degree to which parts of a software system can be reused in the construction of other software systems.
- Compatibility: How easy it is to combine software systems with eachother.
- Efficiency: The degree to which the system treats the resources at it's disposal in an economical way. (This can also be a subdivision of correctness, for example in real-time systems)
- Portability: How easy it is to configure the system to run in different environments
- Ease-of-use: How much effort an end user has to put in to use the system in executing their tasks.
- Functionality: Reflects the functional possibilities of a system
- Punctuality: The degree to which a software system is released when (or before) the users need it.
- Verifiability: How convenient it is to build acceptance procedures, test data and -procedures to trace errors when verifying and validating the system
- Integrity: The degree to which certain areas of the system (program and data) are protected to unauthorized access or modification.
- Economical factor: The degree to which a system is delivered within the budget.


It is simply impossible to maximize all these factors, because some have a negative impact on others:
Integrity/Ease-of-use, Functionality/Economical factor, Efficiency/Portability, Extensibility/Punctuality, ...

So to determine whether or not the software system (of which our code is a part) is 'good' (of high quality), it is very important to carefull weigh these factors against eachother and the desires of the stakeholders. Of course, correctness must always be the most important one.


There are practices that help in maximalizing certain external quality factors: for example; Unit and acceptance testing will augment Verifiability, maybe robustness. Agile methodologies could maximize Punctuality, perhaps the Economical factor, and so on...

Then there are internal quality factors, I think the most important ones have been mentioned already: Cohesion, Coupling, Encapsulation, Abstraction, ...
These can also augment the external quality factors:
High encapsulation, low coupling and high cohesion can help in maximizing reusability.


Now, if we are to narrow ourselves to what is "good code"; I'd have to say: Well encapsulated abstractions that exhibit low coupling and high cohesion. But I think "good code" is not enough to warrant a high quality software system.