Professional PHP Blog

PHP Programming, Web Development, PHP Advocacy and PHP Best Practices.

On the Perils of Inline API Documentation

April 13th, 2007

Travis Swicegood has a post questioning the value of the docblock. I have a deep sympathy with this sentiment.

Even on projects with extensive generated documentation, I find that kind of documentation to be of extremely low value. The problem with inline API documentation is that there is no sense of priority. Developers are encouraged to document every element that can possibly be documented. Then, when the documentation is generated, there is no way to distinguish the important from noise.

Another problem is restating the obvious. When a property or method really is well named, there may not be much more to say in the docblock. But, the mechanics of docblocks invites the programmer to say it anyway. So, you end up with comments like “$widget the widget.”

Duplication is also a significant problem. If you inherit from a base class or you implement an interface, there is a tendency to copy and paste the doc block from the parent to the children. This is an obvious maintenance problem. In fact, this is one of the major problems with comments. If comments restate what the code does, its a form of code duplication. When the code is changed, it requires changes in the comments. In this sense, comments make code harder to maintain.

Lately, I’ve been trying to curb the attractive nuisance aspect of docblock comments by replacing docblocks with comments like

 
// Definition in parent
 

or
 
// docblock intentionally omitted.
 

It would be nice if there were standard abbreviations for things like these. The idea being to eliminate the attractive nuisance of the commentable element by placing a comment there that is not a docblock, and then commenting only the elements where you have something to say.

Well, if docblocks are so bad, what is the alternative? Well, I’ve tried a few, including using a wiki for API documentation. Here is the problem. If duplication between the comment and the code is created by inline documentation, that maintenance problem becomes significantly worse with distance. If the documentation is external to the code, that distance really harms the ability to keep the documentation in sync with the code. So, docblocks are bad, but everything else is worse.

Docblocks were popularized by Sun and Java (or maybe Donald Knuth). But when sun was documenting their Java APIs with docblocks, they had a professional documentation team to do the work. When teams that don’t have a dedicated documenter role use these tools, I think they fall short.

So what is the solution? I’d like to see better techniques and conventions for solving the problems of docblocks: avoiding duplication, avoiding restating the obvious, and avoiding the tendency to docblock everything thats docblockable. Maybe there are more successful documenters out there who are handling these API documentation anti-patterns better than I am. I’d sure like to hear how.

18 Comments »

Software Development Team Diversity

March 26th, 2007

Matt Mullenweg has a post about Hiring Diversity. A successful software project must fulfill many competing goals and factors and meet a wide variety of challenges. Diversity is the combined arms of software development. In my personal experience, the diverse team performs better. A diverse team allows the most appropriate team member to step up to a challenge. The interaction between team members with different points of view helps a project balance competing goals.

Technical Background

A team needs members with a technical background. These guys are the ones that ensure everything works. They can write the hard bits of code, keep everything performing and make sure the code is maintainable. Without these guys, you will have problems. On the other hand, sometimes those with a technical background view problems solving as a puzzle, where the solution is the end in itself.
In my experience, team members with a less technical background are more empathic toward the user community. They view problem solving as a means to a goal. A customer focus is what makes a project successful. Software can be successful despite technical problems, but it cannot be successful if doesn’t meet the customer’s needs. Having some non-technical people helps prevent your resident technocrats from building a system that will service 10,000 concurrent users, but doesn’t meet the needs of the 329 users you have today.
Perhaps at the extreme end of this spectrum is the extreme programming practice of including a customer on the development team.

Experience

In expert versus novice programmers, I make the distinction between skill level and experience. Age, skill and experience often correlate, but not always. Your young apprentice programmers are important to have on a team. They can react faster. Sometimes not knowing better is a bonus. They’ll do things more senior team members don’t want to do. They do things they’re not supposed to do, sometimes for the benefit of the team.
I think people underestimate how long it takes to actually become an expert, as I mention in my previous post. But, then they also underestimate how similar all software projects are. They also overestimate the impact of their toolset. Generally the technologies in the laundry lists that form most job listings are not the critical success factors for that project.
People want a programmer with who can hit the ground running, who is familiar with all of the teams tools, languages and libraries. But, this is a monoculture as well. Sometimes you need people who aren’t from your toolset culture to point out where you have swallowed the hook too deeply or to introduce new tools and techniques from their alternate background. Sometimes their learning process can teach you something.
While some experience is valued in programmers, age sometimes isn’t. However, you need the older, more stable people as well. They keep the young ones from repeating the mistakes of the past. They keep the project on an even keel. It helps to have an older perspective on the team. I think they help keep attention focused on what matters. The tension between the older and younger team members helps keep the team on track.

Traditional Diversity Factors

I have no opinion on the impact of race. I have an opinion about women on software teams. I wish there were more of them. I have worked on software development teams with diverse nationalities. I regard that experience as positive. Different cultures have different tolerances for risk, different respect for authority or tradition. I think cultural diversity on a team is a good thing.

Managing Diversity

Over the years, there have been many methods proposed of matching people with the jobs they are best at. The solution that works best is to ask them. People gravitate toward the tasks that require their special skill sets. Good team management means hiring diversely and allowing that migration. On a well managed, diverse team, people will self select the jobs they are best at. As a result, the diverse team is more resilient and I believe potentially more successful.

15 Comments »

The Problem with Markup Languages

March 14th, 2007

Chris Shiflett has a post today, Allowing HTML and Preventing XSS. The problem is how to allow users to format their contributed content without introducing security vulnerabilities. The answer is usually some sort of markup language or filtering and sanitization of HTML.

BBCODE was designed for this purpose. There is no actual standard, but the core syntax seems fairly uniform. It’s good for those used to forums, where it seems to norm.

HTML markup is nice because it is a standard, even if varying subsets are supported. Learning a little HTML isn’t going to hurt anyone, at least for the next 20 years or so. The problem is that HTML was never intended to be hand edited. The syntax is not the most inviting, and different HTML-like markup languages handle whitespace differently than the HTML standard.

Wiki markup syntaxes were designed to be human friendly. The main problem I have with wiki syntax is that there is no standard. It seems like every wiki has a different way to formulate a link, for example. I guess there is some progress with Wiki Creole, but I still have a bad taste in my mouth.

The other problem I have with wiki markup is that I find it to be non-deterministic. When I edit any given wiki and try to use more than basic formatting, I never know what I am going to get. Most of the markup processing engines for these wikis are impenetrable morasses of regular expressions. It can be hard to gauge interactions. Are you really sure they are secure?

Speaking of impenetrable morasses of regular expressions, have you ever looked at WordPress’s input path? I’m sure every one with a WordPress blog who likes to blog about PHP code knows that it is a code eater. I’ve been particularly disappointed with WordPress in this area. Most the “code formatting” plugins still have problems protecting code from WordPress’ heavy hand.

But the WordPress preg_replace gauntlet doesn’t just mangle code. I have a post which has been sitting in draft mode for several weeks because I can’t figure out how to give it the proper markup. WordPress is somehow taking my perfectly balanced input markup and producing “unbalanced” output markup. I haven’t yet tracked down the problem to either submit a fix or to do a good bug report. Frankly, I’m not looking forward to trudging through all those regular expressions.

In Chris’ post, he takes the regular expression approach. Folks in the comments have pointed out a few problems with his approach, including the problem of interleaved tags. If you can’t tell by now, I am not a fan of the regular expression gauntlet approach to markup languages. I prefer a defined syntax and a traditional computer science style parser (which may use regular expressions).

The other must-have is a preview option. With so much variation in markup languages, not having a preview leaves the user to play Russian roulette with their submitted content. I’ve talked about that before in the usability of input filtering. This is another area where WordPress leaves the user high and dry.

The complex input path in WordPress combined with its reliance on global variables seems to leave it unable to do an in-page preview. The admin area preview is an IFRAME so that it launches a separate request. The various live preview plugins are JavaScript based and don’t work when it is disabled. They also don’t pass the input through the same input path that WordPress uses, so they are not a true preview.

I don’t mean for this to be a WordPress rant, on the whole, I like WordPress. Rather, I just wanted to point out how hard it can be to do good input filtering, that is safe, reliable, deterministic, and usable.

14 Comments »

Firefox Extensions for Web Developers

March 8th, 2007

I prefer Safari for my casual web browsing on the Mac, but for web development, nothing beats Firefox. (Firefox beats IE hands down on Windows.) Firefox’s openness and the Firefox plugin architecture means that there is little that you cannot find out about a web page with a Firefox add-on. I’ve tried [...]

33 Comments | Read the full post »

Yahoo YUI wins JavaScript Library Wars

February 23rd, 2007

There is huge web development news from Yahoo today. Yahoo is offering free hosting for YUI components, both JavaScript and CSS. I’ve been favoring the YUI, but this is a great boon. One big drawback to AJAX is Page loading performance. I’m betting that the Yahoo infrastructure can serve these files [...]

20 Comments | Read the full post »

Delphi for PHP

February 23rd, 2007

I have to comment on this week’s annoucement of Delphi for PHP. I was a Delphi programmer for about 5 years before taking up PHP about 6 years ago. What a convergence.
I have a great fondness and respect for the old Object Pascal based Delphi. Delphi’s VCL has been influential, inspiring the [...]

40 Comments | Read the full post »

Managing Open Source Projects

February 22nd, 2007

I ran across How Open Source Projects Survive Poisonous People (video) and Producing Open Source Software (book). Anyone know of any other interesting open source project management resources?

6 Comments | Read the full post »

Free Software for Mac OS X

February 22nd, 2007

The software that comes with OS X is very capable. The mundane applications that come with OS X, such as the Finder, Preview, and Disk Utility can do some surprising things. I’ve been using Macs for 20 years and I’m still learning new tricks for these programs.
But, the installed apps can’t do everything. [...]

25 Comments | Read the full post »

How to Transfer Mac OS X Application Data between Computers

February 16th, 2007

Its been a long time coming, but I finally got a new Mac. I’ve personally owned a Mac of one sort or another since 1987, but I didn’t start using a Mac full time for work until around 2000. I’ve been going through the process of setting up the new machine.
I decided to start [...]

82 Comments | Read the full post »

OOP is Mature, not Dead

January 7th, 2007

I ran across an interesting series of blog posts by Karsten Wagner claiming that OOP is dead (part 2 and part 3). The premise behind these posts is that OOP has failed to deliver and that it is on the decline in favor of more functional or meta programming techniques. Maybe its true [...]

25 Comments | Read the full post »

« Previous Entries
Next Entries »
    Subscribe Feed
    Share Subscribe to this blog…
    Share Bookmark or share this page…
  • About

    My name is Jeff Moore. I'm a PHP programmer living in San Francico and working for a startup.

    More about me…

  • Categories

    • Agile Methods (14)
    • Mac (14)
    • Misc (18)
    • Open Source (14)
    • PHP (99)
    • Software Design (29)
    • Usability (14)
    • Web Design (20)
  • Recent Comments

    • Writing an XPath expression evaluator  7
      JDM Cars, Alva Sisk, teeth falling out dream [...]
    • PHP Games  63
      Furniture Manufacturers, Jason Pierre-Paul Jersey, Voncile Grizzel [...]
    • PDO versus MDB2  31
      Morton Deliso, Marquis Valakas, Beatriz Elifritz [...]
    • Why PHP is easier to learn than Java  48
      Betty Wager, Orville Kotrys, Esperanza Mcpeck [...]
    • Friendster wrapup: does MySQL scale  29
      Clemente Michaux, Kandra Noriego, Earl Skowronski [...]
    • Enterprise PHP  42
      Hoyt Origer, atomboygame, Luna Cerny [...]
    • Comparing PHP with other languages  38
      polštinap?eklad, polštinap?eklad, php developer [...]
    • Looking Towards the Cloud  65
      spin, Serina Doshier, Graciela Guisinger [...]
    • Working with PHP 5 in Mac OS X 10.5 (Leopard)  241
      Rory Teich, Lady Gaga, Tommy Staude [...]
    • Richard Thomas  27
      Hedwig Larcher, Carlos Cherenfant, Kurt Vagliardo [...]
  • My Other Stuff

    • Lively Debate
      My blog on Politics and non-technical topics
    • Web Application Component Toolkit
      PHP MVC Framework
  • Other PHP Blogs

    • Dynamically Typed
    • Jason E. Sweat
    • John Lim
    • Marco Tabini
    • Marcus Baker
    • Norbert Mocsnik
    • PHP Patterns
  • Site

    • Archives
    • Log in
  • Search