symmetry

Parallel Things Must Look Parallel

If two functions do analogous work, they must have analogous structure. Same parameter order. Same return shape. Same error handling pattern. Same naming scheme. No exceptions. No "well, this one is slightly different because..." -- stop. If the work is parallel, the code is parallel. Period.

Symmetry is not aesthetics. It is how a reader builds a mental model of your codebase. When create_user and create_product have the same shape, the reader learns the pattern once and applies it everywhere. When they differ -- different parameter order, different return type, different error wrapping -- the reader must re-learn the pattern for every module. That is a tax on every person who touches the code for the rest of its life.

The Symmetry Rule

If two things do analogous work, they must have analogous structure.

This applies at every level:

• Function signatures -- same parameter order, same types, same defaults
• Return shapes -- same envelope, same field names, same error representation
• Error handling -- same wrapping strategy, same logging, same recovery pattern
• Naming -- same verb/noun scheme, same prefixes, same suffixes
• File structure -- same sections, same ordering, same grouping
• Test structure -- same setup, same assertion style, same teardown

CRUD Symmetry

CRUD handlers are the most common symmetry violation. Every handler for a resource must have identical structure: same logging calls, same error handling, same response shape. If create logs the operation, delete logs the operation. If read wraps errors in a ServiceError, update wraps errors in a ServiceError.

GOOD -- symmetric CRUD:

class UserService:
    def create_user(self, data: CreateUserInput) -> ServiceResult[User]:
        logger.info("creating user", extra={"email": data.email})
        try:
            user = self.repo.insert(data)
            return ServiceResult(data=user, error=None)
        except DatabaseError as exc:
            logger.error("failed to create user", extra={"error": str(exc)})
            return ServiceResult(data=None, error=ServiceError.from_exception(exc))

    def get_user(self, user_id: str) -> ServiceResult[User]:
        logger.info("getting user", extra={"user_id": user_id})
        try:
            user = self.repo.find_by_id(user_id)
            return ServiceResult(data=user, error=None)
        except DatabaseError as exc:
            logger.error("failed to get user", extra={"error": str(exc)})
            return ServiceResult(data=None, error=ServiceError.from_exception(exc))

    def update_user(self, user_id: str, data: UpdateUserInput) -> ServiceResult[User]:
        logger.info("updating user", extra={"user_id": user_id})
        try:
            user = self.repo.update(user_id, data)
            return ServiceResult(data=user, error=None)
        except DatabaseError as exc:
            logger.error("failed to update user", extra={"error": str(exc)})
            return ServiceResult(data=None, error=ServiceError.from_exception(exc))

    def delete_user(self, user_id: str) -> ServiceResult[None]:
        logger.info("deleting user", extra={"user_id": user_id})
        try:
            self.repo.remove(user_id)
            return ServiceResult(data=None, error=None)
        except DatabaseError as exc:
            logger.error("failed to delete user", extra={"error": str(exc)})
            return ServiceResult(data=None, error=ServiceError.from_exception(exc))