The docblock dilemma — my dying affinity with PHP docblocks

Life as a developer is a constant journey, a progression of learning new technologies and evolving best practices. Something you thought was great 3 years ago may now be something you can’t help but refactor out each time you revisit old code.

Chances are the same thing that you now hate was something you declared as the “only way to live” in a previous version of your coder life.

Docblocks have often been subject to this type of dogmatic discussion, mainly because of what they are — subjective descriptions that aim to add clarity, but also sail unnervingly close to the actual implementation of code.

If you’re using docblocks to auto-generate API docs for your codebase then they offer a useful way of including human-friendly documentation alongside your classes and methods — but for most they are simply a giant, formatted comment planted at intervals throughout the code.

And herein lies the problem — docblocks are related to the code, but they aren’t the code. As in, they don’t affect whether the code works or whether it doesn’t. They are purely designed to try and make the codebase more elegant and easier to work with.

Ask me not long ago and I would have told you “of course, all code needs a corresponding docblock — what are you some kind of script kiddie”. But more recently I’ve started having this dilemma…

Here are three things that have made me question the purpose of writing docblocks.

1. Duplicating what is in code risks describing things incorrectly

Once-upon-a-time in PHP there was no way of defining what your classes and methods expected to receive — after all a variable is a variable, right. At this time docblocks were essential for describing the expected type for each param, as well as what type the method was going to give you back.

No wonder we all got so uptight about writing docblocks for every single method!

However, fast-forward to the world of PHP 7 and — like it or not — type hinting of arguments, properties (PHP 7.4), and return-typing of methods is both natively supported and common place.

So what does that mean for docblocks? Well, to put it simply it means that if your code uses strict typing then writing additional docblocks means you may be repeating yourself.

Now I’m not the sort of person to say don’t do something because it will take a bit longer…but the real concern here is that every time we need to manually remember to update a docblock to match the changes in our actual code, it increases the risk that those docblocks actually won’t be correct any longer.

And as soon as this starts happening then our codebase will lose credibility fast and those docblocks that once offered us some benefit now work to detract from the code quality.

2. Ad-hoc usage reduces the aesthetics of the code

It’s all well and good using native typing in newer versions of PHP, but the reality is that there are elements of this that don’t still fully cover everything you might want to say about your code.

For example, if your method returns an array then great, go ahead and use the array return type. But what if your method returns an array of User objects? Using a docblock you would simply write:

* @return User[]
public method getUsers(): array

In his popular article about docblocks in PHP, Andreas Möller lays out his principles for working with docblocks. Quite simply, if they add value then use them — if they don’t add value then remove them.

For a while this is the principle I tried to use in my code, however it fell down in one particular area…aesthetics!

Yes, as ridiculous as it may sound I came to the realisation that I simply liked the way docblocks looked in my code when they were applied in a consistent manner. They offered a way of visually separating the methods in my classes. They had a standardised format which appealed to my sense of organisation.

And by removing docblocks completely — well, of course I lost the visual separation between my methods, but at least I was still following a particular style consistently. By applying a more ad-hoc approach to docblock usage (ie. only when they “add value”) all of a sudden my code looked…messy!

For some, the fact I even wrote this down may be laughable — but others may sympathise with my dilemma, the eternal balancing-act between a nice idea and the inevitable caveats.

3. Documentation writing is a specific skillset

Up to now I have only really talked about docblocks in terms of documenting types in your classes/methods, but for some they like to really go to town by writing novel-esque descriptions as part of their docblocks.

Whilst this is all dandy when codebases are auto-generating API docs and have a capable product team behind them, let’s please remember that writing documentation is a specific skillset in itself and that we should not expect all developers to be able to write documentation well.

Hell, I’ve known developers who can effortlessly write a SOLID back-end but can barely string a sentence together…and that’s fine!

Yes it is important that developers think carefully about their code (I call this “crafting”), but if we demand that all docblocks must contain a pretty description of what a method does or what a parameter is, then we’re going to end up with descriptions that are either pointless, or worse, plain wrong.

And that reduces the quality of our codebase.

In conclusion

As with anything in the world of a software developer, every approach has it’s inevitable trade-offs. With docblocks we are balancing structure vs repetition, consistency vs redundancy, descriptiveness vs pointlessness.

I still haven’t fully figured out what my views on docblock best practices for modern PHP are. The beauty of our perpetually progressing industry means that if I ever do figure it out, chances are they’ll change again pretty soon.

Written by

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store