Tim Hentenaar's Blog

Apr 01, 2014 19:30

On Matters of Style

Since the dawn of man, people have had varying methods of doing things, and have always been quick to beat each other over the head in favor of their own preferred method. As an engineer, I hear lots of discussion on "coding style," and the level of analness exhibited by various people, from colleagues to random bloggers on the web can be quite shocking.

Is there really one, true way to write code? I think not. It's an issue that's been written about, danced around, debated, rebelled against, shot down, and reborn about every decade. These sort of discussions were taking place even before the standardization of ANSI C. The issue of brace placement in particular has plagued the languages that use them for at least three decades.

Let's take a look at how some of these things are regarded in a couple of different development ecosystems, and then even though I ain't Jerry Springer, I'll conclude with some final thoughts.

PHP

I've been in a few PHP shops in my day, and I've worked on quite a few PHP projects. I've heard the adage that PHP is quite simply "the easiest programming language to learn." This is a statement I could never agree with, however, as PHP is not a bona fide programming language, but a gross amalgamation of various features gleaned from other scripting languages, and implemented in wildly varying and often inconsistent ways.

As far as static analysis tools go, the ones I've encountered most frequently are: PHP_CodeSniffer, PHP Mess Detector, hell, there's even a code style fixer to reformat your code before you wind up losing your sanity over it. This is the realm where I have encountered the most analness over coding styles. I wonder why that is...

Although there is no official PHP "coding style" there's a set of coding style guidelines referred to as PSR-2 that some people love to push. It is written and maintained by the PHP Framework Interop Group, the ultimate goal of which is to encourage adoption of common conventions between the developers of various PHP frameworks. Although, each framework tends to have its own "style guide," and tend to deviate in various ways from PSR-2: (Note the gratuitous use of the word standard in this and the links below. I'll get to that in my final thoughts, just keep it in mind.)

I recall having had rather heated discussions with colleagues (contractors, mainly) at one point, who swore up and down that PSR-2 was the one, true way to write PHP code. Knowing that this is a common example of fallacy, I would ignore their belligerent attacks at first, but there always comes a certain moment when you just can't take it anymore. It was at that point, when I started to probe and question the rationale behind their obviously subjective and emotion-fueled viewpoints. The only reply I received was a link to this website.

When I view that site, the section immediately after Getting Started is.... Wait for it... Code Style Guide! I must therefore assume that the author of the website in question believes that "coding style" is an issue of paramount importance, considering the prominence of its placement on the site. This particular site seems to be oriented specifically towards newcomers to the PHP sphere, and PHP developers that may have been "lead astray by all of the bad practices and insecure code on the net". However, the author unforutnately fails to elaborate on the intended meaning of bad practices and insecure code, or to cite examples thereof.

I can only speculate that the author of the aforementioned site has dealt with a lot of PHP code that was absolutely horrid in his opinion, finally got fed up with it, and decided to try to do something to combat what probably seemed like a growing trend in his eyes. Can't fault him for that. But, is that really the biggest problem faced by PHP developers? Somehow, I think they have bigger fish to fry.

Ruby

I was introduced to Ruby by the late Jim Weirich years ago, and have found it to be an interesting scripting language for sysadmin tasks as well as web development. I've worked on a few Ruby projects over the years, some of which can be found in my GitHub repos. Never once have I heard the amount of quibbling and whining that I've had to endure in the PHP arena. Not to mention, Ruby is an OO language, designed for general purpose scripting. PHP isn't and wasn't. Ironically, Ruby and PHP were both developed in 1995.

Like PHP, Ruby is an amalgamation of features gleaned from other scripting languages. In the case of Ruby, however, these things were blended in a more uniform way, with an overall focus on ease of use and simplicity. It's also of interest to note that, to my knowledge, the PHP developers that I've introduced to Ruby have never looked back. :P

Although it seems the Ruby community isn't in any way as anal about "coding style" as their PHP counterparts, there are still a few people publishing similar things, although there is no official Ruby "coding style":

This one is quite extensive, which to be honest is quite shocking, and it even comes complete with it's own whining tool. It reads a lot like its PHP counterparts.

Ruby is, by design, a simple and elegant language. What is the source of the perception that the Ruby community at large needs a "style guide"? If that were truly the case, there would already have been an official guide.

C

There was a lot of discussion on usenet in the late 80s and early 90s, about "coding style" recommendations, as well as may books written before and after the standardization of ANSI C.

Most people look to the wisdom of the creators of the C language, Brian Kerninghan and Dennis Ritchie, and the way they wrote the examples in their books to guide them on how to write C. When I learned C, I did so from the same book (The C Programming Language) and thus had incorporated that very style (affectionatly called K&R Style) into my own. Of course, my style follows the examples in the 2nd Edition book which was written for ANSI C, and not the original book from the late 1970s.

Here are a few of the "coding style" documents that have been otherwise written for C.

General

which are both decended from: Indian Hill C Style and Coding Standards

Per Project

MISRA-C

This is an example of a coding standard, and not a style guide. Its inclusion here is merely for demonstrative purposes about what comprises standards versus a style guide. These standards come from MISRA (Motor Industry Software Reliability Association) and are targeted specifically at the embedded engineering community within the automotive industry. It's important to note that this is unfortunately a closed standard and cannot be directly quoted, due to license encumberment, without express consent from MISRA. Rumor has it that the MISRA-C standards are widely accepted in the aerospace, telecom, transportation, medical and defense sectors.

This standard draws heavily on MISRA-C as well as other ISO standards, and is targeted primarily at development of mission critical flight software. The Power of Ten, also from JPL and published in IEEE Computer (June 20 06, pp. 93 - 95) is also a worthwile read, as it is incorporated into the coding standards given below.

In these sort of standards, it's important thing to note that the rationale for each rule is clearly explained.

Final Thoughts

Even in the late 1970's, matters of "coding style" were being discussed. The Elements of Programming Style is one of the first texts I'd read on the matter. In it, the authors lay out simple maxim-like rules for keeping code readable, and I find that they still hold relevance today (even though the examples are in FORTRAN and PL/I.) These principles are well-rooted in common sense. I fear, however, that the required simplicity for producing successful guidelines seems to continually elude the authors of present-day "coding style" documents. There seems to be more focus on the minutia of bracing styles and punctuation than on writing clear and readable code.

These documents also tend to be very vague in their rationale. This is the key difference between "guidelines" and "standards." A standards document will clearly articulate the rationale behind each rule or guideline, and must typically undergo a formal adoption process by a standards organization after lots of scrutiny (i.e. peer review, research, etc.) in a working group.

Furthermore, why the hell do we need such thing in the first place? I've heard a litany of arguments on the subject, and in some cases, the need for real standards is very clear. Take, for example, the MISRA-C standard. It has a very specific target audience, and a very specific intent behind its design, along with a clearly-defined rationale for its use. It's designed for code that will be used in safety-critical applications (i.e. where a software fault may result in a catostrophic loss of life.) However, where someone puts a brace, or how someone indents their code in your precious website isn't going to cause widespread panic, massacres, or acts of genocide; unless of course you're an anal-retentive coding style perfectionist. As a general rule of thumb, developers tend to emulate the style of existing code when making additions to it anyhow and if not, they might not be the team player you figured them to be. By definition, the anal-retentive people who continually push stylistic issues are not team players.

In a few places I've been, I've noticed that people tend to use "lack of coding standards" (referring to style guidelines) to explain-away bad architecture, and simultaneously push their specific opinion about what constitutes "good code," by writing some vague guidelines and calling it a "standard". Then they claim: If we had just followed this standard... There is no substitute for good architecture. Even if the windows are intact, there's no guarantee the house won't collapse if the foundation is shaky. As for what constitutes good architecture that's a subject for a future article. I'm not trying to write a book for God's sake. :P

One of the most curious arguments I've ever heard in attempts to push certain code styles is the IDE can auto-format to whatever we decide. This argument is prima facie void for a few reasons. First, not everyone uses an IDE. Second, accepting any largely-reformatted code into the codebase is extremely risky. If the reformatting process breaks something, it may not be caught right away, and worse, if it makes it to production, finding the problem will be hell in a fairly substantial codebase. Third, everyone else working on that particular code may wind up having to completely redo all of their changes, since they will no longer merge cleanly with the mainline branch. If reformatting is to be done, it should be done only with proper planning, and coordination, doing a bit at a time and keeping in mind that there is no business value in it.

Another such argument is the insinuation that without code style standards, it will be more difficult for people working on the project to cooperate. People have been working together on development projects ever since people had the ability to develop anything at all. Thus, it will be no easier for them as a whole than it is already, assuming that they have found the balance and synergy you can observe in a working team. As programmers, we have to deal with different coding styles on nearly every project we work on, especially in the world of Open Source. It's a fact of life for us, and we learn to cope rather well.

You also have to consider the effect the coding style zealots tend to have on a team. If the team shares the same viewpoint as the zealot, then the effect is minimal, and may even be positive as it will reinforce the views they already hold. If not, however, the effect will be largely negative. The team will view the anal-retentiveness of said zealots as a hostile attack on their work, and by extension, themselves. In this context, tools like PHP_CodeSniffer are used to whine and complain whenever the code doesn't conform to the zealot's preferred style. In this context, the zealot and his tools become yet another roadblock on the developer's path to delivering his or her code.

Every hurdle you place between the developer and the goal line only serves to distract them from what they should be doing, which is of course: delivering software. What I've observed is that the more anal such things are, the more frustrated the team becomes, and the slower the team generates output. Ultimately, the team winds up coding to appease the tool rather than to meet the goal, simply to avoid all the whining and brow-beating. Most companies I've worked with want to hire talented and creative people, yet some have allowed this sort of analness which only serves to stifle creativity under the guise of improving code quality.

We also have to look at these two words: code quality. This seems to be among the top terms the zealots use to justify their position. But, how do you quantify it? By what standard do you judge it? Where do you set the target? Compliance with the "style guidelines?" -- That's absurd. Number and severity of reported defects? -- That might be a piece of the puzzle, but defects are an assumed risk of development, so their presence alone isn't enough to judge the quality of the code. One must also evaluate how well suited the code is to the purpose for which it was written, how difficult it is for the reviewer (meaning: someone other than the author) to understand the implementation and work with it, catch unintended side-effects, undefined behaviors, etc. Most of these things have little to do with asthetics (as long as the code in question isn't a massive one-liner or purposefully obfuscated.)

O great coding style "gurus," how do you propose we quantify your vision of code quality other than deviation from _your_ pet coding style? Take a peek at the quality model specified in ISO/IEC 9126 and its successors for some ideas of what established models for software quality look like. There's a lot more to it than simple asthetics.

I, for one, don't put much stock in self-proclaimed gurus. Especially ones who are trying to sell you copies of their books as a cure-all for your software quality ailments. I maintain that any sort of style guidelines must be adopted by the team as a whole, willingly, in order to be of any value. They absolutely must fit the project, and they must be flexible and rational enough not to drive the team to the brink of madness. How's that for a standard applicable to writing a coding style guide? :P

Finally, no matter what stance you take with regard to coding style, just keep it simple, stupid. We all value consistency, but we don't all enjoy quibbling over minutia. We are not borg, we will not be assimilated, resistance is not futile, we will never produce perfection, and there is no perfect coding style.