Simplify ActivityPub's Follow Method: Better Return Types

Hey everyone, let's dive into a discussion about making the Following::follow() method in the WordPress ActivityPub plugin a bit more streamlined and user-friendly. We're talking about simplifying its return types to make the code easier to understand, use, and maintain. This should make things much more predictable for all of us. Let's break it down!

The Problem: Overly Complex Return Types

The Following::follow() method and the related follow() function currently have some pretty complex return types. This makes it harder to understand exactly what you can expect back from these functions, which can lead to confusion and potential bugs down the line. Let's face it, nobody wants to spend hours debugging code because they weren't sure what a function was going to return. The goal is to make the code more predictable, more reliable, and easier to work with.

Current Return Types - A Quick Look

• Activitypub\Collection\Following::follow() method: This method can return several different things, depending on what happens during the process. When an invalid actor is used or retrieval fails it returns WP_Error. If the follow activity is successfully added it returns int|false from add_to_outbox(). If the user is already following the actor it returns WP_Post.
• Activitypub\follow() function: This function is similarly complex, potentially returning an int, false, WP_Post, or WP_Error. That's quite a range, right?

This variety of return types makes it tricky to write code that handles all possible outcomes gracefully. You have to account for several different scenarios, which increases the chances of overlooking something and introducing errors. The goal is to simplify this to make it much easier to work with these functions and make sure you can handle any outcome easily.

Discussion: Why Simplify?

This issue was raised in a pull request, and the suggestion was to limit the return types to just two to reduce complexity. The aim is to standardize the return types to make the code easier to understand, use, and maintain.

Benefits of Simplifying

• Improved Code Predictability: When you know exactly what a function can return, it's easier to anticipate its behavior and write code that responds correctly. This predictability helps reduce the chances of unexpected errors. Knowing exactly what to expect from a function is half the battle.
• Consistent Error Handling: Simplifying the return types allows for more consistent error handling. You can check for errors in a standardized way, making it easier to catch and handle issues. This leads to more robust code.
• Enhanced Developer Experience: When working with a codebase, a simplified API improves developer experience. Knowing what to expect from functions and methods means less time spent debugging and more time spent building cool features. Developers will appreciate the cleaner design, and it will also speed up development overall.

Proposed Solution: Standardizing Return Types

The proposed solution is to standardize the return types to a maximum of two types, such as int| WP_Error or bool| WP_Error. This would make the codebase more maintainable and reduce confusion about the expected return types. The main idea is to make these functions more predictable and easier to use. This simplicity is the key.

The Value of Two Return Types

Let's say a function can either return an integer (e.g., a success code) or a WP_Error object (if something goes wrong). This is a very common and practical pattern. It allows you to quickly check if the function succeeded or failed and handle the error appropriately if it failed. This can also use a boolean to represent whether the function has succeeded or failed, if something goes wrong it will return WP_Error, and this makes it very easy to use and can handle any situation properly. A bool is great for the success/failure check because the code becomes easier to read and understand.

Code References to Keep in Mind

Let's take a look at the code references that are relevant to this discussion. It's good to know where these methods and functions are used to understand how these changes would affect the broader codebase. This is a really valuable part to understand the core concept of the topic.

• includes/functions.php:1556: The follow() function is the main function and one of the places where these return types are used. It is a central function, which means any changes here will have a significant impact.
• includes/collection/class-following.php: The Following::follow() method is the core method, and this is where we have the complexity. The goal is to improve this method's return type to make it easier to use.
• includes/functions.php:1471: The add_to_outbox() function is an important function because it directly affects the Following::follow() method. It returns int|false, and the goal is to simplify this to ensure a more consistent and predictable experience.

Understanding these code references is important for seeing the scope of the changes and how they will affect the WordPress ActivityPub plugin. By simplifying the return types, we can make the whole codebase more reliable, which is a win for everyone.

Conclusion

By simplifying the return types of the Following::follow() method and related functions, we can make the codebase easier to understand, use, and maintain. This will lead to more predictable code, consistent error handling, and an improved developer experience. It's all about making things simpler and more effective. Standardizing to a maximum of two return types is a great way to achieve these goals. The proposed changes are a step in the right direction towards a more user-friendly and robust plugin. Thanks for following along, and let's keep the discussion going!