Note: Laravel’s obsessive comment style

Nov 11, 2022

In the early-ish days of the PHP framework Laravel, the author Taylor Otwell took an obsessive approach to code consistency. Not only did every method include a docblock with a description, but each description was exactly three lines long, and each line was exactly three characters shorter than the previous line.

Example

Image source

Not only was he obsessively documenting his code, but he was so dedicated to the aesthetics of his docblocks, that he was — I have to assume — making word selections in order to achieve it.

In a Reddit thread, he replied:

It is indeed intentional. I'm not sure if it's awesome or neurotic either... :)

Also, it is not just config files - it is the entire framework.

Config files are the first impression of the framework once you have it installed. So, I want it to be pleasant to the eye. The symmetrical comments help with that. I don't want your first impression of the code to "appear" disorganized or something. I dunno. It's kind of crazy. I do it with all of the Laravel core code. If it doesn't look pleasing to the eye, I keep working on it until it is.

I’ve never seen anything like it before or sense.

As the project has grown, and probably started to include more contributors, it seems this pattern has relaxed, however the code is still meticulously organized.

Sources

Tags: annecdote