Tag: best practices

Toptal: The Suddenly Remote Playbook

Toptal is one of the great companies that I have my eyes on.  If you haven’t heard of them, here’s a brief intro:

Toptal is an exclusive network of the top freelance software developers, esigners, finance experts, product managers, and project managers in the world. Top companies hire Toptal freelancers for their most important projects.

I’ve had some interactions with the company in the past, and I’ve heard plenty of stories from other people.  These guys definitely know what they are doing.

And if you don’t believe me, here’s some proof for you.  The COVID-19 pandemic forced a lot of companies, teams, and people to work remotely.  Some were ready for this, but most had to make major adjustment.  Many are still struggling.  Toptal though is not one of them.  They’ve been doing remote work for a long time now.  Lucky for the rest of us, they’ve shared a lot of that in a rather concise, to the point, easy to read document, titled “The Suddenly Remote Playbook“. It is a playbook for sustaining an enterprise-grade remote work environment, from the world’s largest fully remote company.

It doesn’t matter whether you are just starting with the remote work, or have been doing it for a long time, I promise you, you’ll find plenty of useful information in there.

From the simple and direct quotes like:

People are the most important element of any company, remote or not.

To an impressive list of tools like:

  • Slack
  • Grammarly
  • Zoom
  • Krisp.ai
  • Google G Suite
  • Miro
  • Collabshot
  • Loom
  • Trello
  • Asana
  • Confluence
  • Zapier
  • … and more.

Strongly recommended for reading, studying, and implementation!

A practical guide to writing technical specs

Writing technical specifications is difficult.  Writing good technical specifications is even more so.  Here’s an excellent practical guide from StackOverflow on how to write technical specifications, which have everything needed, yet not being too excessive or vague.

In the comments, there are a few additional suggestions and links to other similar guides.

The only way this could have been better, if they included a ready-made template with all the described sections, so that one could just fill it in and be done with it.

PHP CodeSniffer: Ignoring rules

PHP CodeSniffer is a great tool for making sure all your code is consistent with a set of rules and guidelines. However, there are cases, when you need to ignore the rules for a particular code snippet. For example, when you are working with third-party frameworks or libraries.

CodeSniffer provides a number of ways to do this. Until today, the following worked well for me:

// @CodingStandardsIgnoreStart
echo "Here goes some code that breaks the rules";
// @CodingStandardsIgnoreEnd

This is particularly useful for code within functions and methods. But what if you need to ignore a particular rule for the whole file, especially in places like method names, which are difficult to surround by starting and ending annotation tags?

Here’s an example that worked for me (thanks to this comment for the solution):

<?php
/**
 * @phpcs:disable CakePHP.NamingConventions.ValidFunctionName.PublicWithUnderscore
 */

The only bit that you’d probably need now is an easy way to find the name of the rule from the CodeSniffer output. The usual output of “./vendor/bin/phpcs” looks like so:

FILE: src/Model/Table/KeysTable.php
-----------------------------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
-----------------------------------------------------------------------------------------------------
 53 | ERROR | Public method name "KeysTable::_initializeSchema" must not be prefixed with underscore
-----------------------------------------------------------------------------------------------------

But if you run it with the “-s” flag (thanks to this comment), CodeSniffer will add sniff codes to all reports. Here’s the same example with “./vendor/bin/phpcs -s“:

FILE: src/Model/Table/KeysTable.php
------------------------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 53 | ERROR | Public method name "KeysTable::_initializeSchema" must not be prefixed with underscore
    |       | (CakePHP.NamingConventions.ValidFunctionName.PublicWithUnderscore)
------------------------------------------------------------------------------------------------------------------------------------------------------------------------

And that’s the code sniff rule that you can add to the ignore annotation tag at the top of your file, like I’ve shown above.

Google: How to do a code review

Google is sharing “How to do a code review” as part of its engineering practices. Unlike many similar guides online, I find this document to be a lot more comprehensive. It covers both the technical bits of the process, as well as suggestions that improve overall team communications and efficiency.

A particular type of complexity is over-engineering, where developers have made the code more generic than it needs to be, or added functionality that isn’t presently needed by the system. Reviewers should be especially vigilant about over-engineering. Encourage developers to solve the problem they know needs to be solved now, not the problem that the developer speculates mightneed to be solved in the future. The future problem should be solved once it arrives and you can see its actual shape and requirements in the physical universe.