Nugsoft Developer Guides

10. Documentation

Comprehensive and clear documentation is crucial for maintaining high-quality codebases, enabling developers to understand, modify, and extend your code easily. At Nugsoft, we follow strict documentation standards using PHPDoc and other tools to ensure our code is well-documented and maintainable.

1. PHPDoc Standards

Use PHPDoc for documenting all functions, methods, classes, and properties. Properly documented code enhances readability and helps IDEs provide better autocomplete, type-hinting, and error-checking features.

  • Always document the purpose of the method or function.
  • Document all parameters and their types.
  • Specify the return type of the method or function.
Example
/**
 * Get the user's name.
 *
 * Retrieves the full name of a user by concatenating the first and last names.
 * This method assumes that the user's name has already been set.
 *
 * @param bool $capitalize Whether to capitalize the name or not. Defaults to true.
 * 
 * @return string The formatted full name of the user.
 */
function getUserName(bool $capitalize = true): string {
    $name = "{$this->firstName} {$this->lastName}";

    // Capitalize name if required
    return $capitalize ? ucwords($name) : $name;
}

PHPDoc Best Practices:

  • Use descriptive summaries: Start with a brief description of what the function/method does.
  • Param descriptions: Describe each parameter, its type, and purpose.
  • Return types: Always indicate the return type and describe what is being returned.
  • Use consistent formatting: Maintain consistency in all PHPDoc comments throughout the codebase.

2. Inline Comments

Use inline comments sparingly but effectively. Comments should explain the why of the code, not the what. Inline comments are useful for describing complex logic, decisions, or non-obvious code sections that might be difficult for others to follow at first glance.

Example
// Fetch the user from the database by their unique ID
$user = getUserFromDatabase($userId);

// If the user doesn't exist, throw an exception
if (!$user) {
    throw new Exception("User not found for ID: $userId");
}

Inline Comment Best Practices:

  • Use comments to explain complex logic: If a piece of code is complex or contains a unique approach, explain why you’re doing it.
  • Avoid redundant comments: Comments like // Increment counter for $i++ should be avoided, as the code itself is self-explanatory.
  • Keep comments up-to-date: Outdated comments can lead to confusion and should always reflect the current logic.

3. API Documentation

For documenting APIs, especially for RESTful or HTTP-based services, automated tools like Swagger (OpenAPI), postman should be used. Swagger provides a standardized, interactive way to document APIs, making it easier for developers and consumers to understand the available endpoints, request formats, and response structures.

API Documentation Best Practices:
  • Use Swagger annotations within your PHP code to describe the API routes, parameters, and responses.
  • Maintain accuracy: Ensure the generated API documentation is always in sync with the actual API implementation.
  • Use descriptive endpoints and request methods in your API design, which should be clearly reflected in the documentation.
Example Using Swagger-PHP Annotations:
/**
 * @OA\Get(
 *     path="/users/{id}",
 *     summary="Get user details",
 *     description="Returns the details of a user by their ID.",
 *     @OA\Parameter(
 *         name="id",
 *         in="path",
 *         required=true,
 *         @OA\Schema(type="integer")
 *     ),
 *     @OA\Response(
 *         response=200,
 *         description="Successful operation",
 *         @OA\JsonContent(ref="#/components/schemas/User")
 *     ),
 *     @OA\Response(response=404, description="User not found"),
 * )
 */
public function getUser(int $id) {
    // Get user details
    return response()->json($this->userRepository->findById($id));
}

Tools for API Documentation:

  • Swagger (OpenAPI): Generates a structured, interactive API documentation based on OpenAPI specifications.
  • Postman Collections: Use Postman to organize and export API requests as a collection for easy sharing and collaboration.
  • API Blueprint: An alternative to OpenAPI for creating API specifications.

Adhering to these documentation standards helps keep the codebase organized, reduces misunderstandings, and improves collaboration across teams.

Back to Top