클린 코드 (주석)

dasd412·2022년 7월 19일

클린 코드 적용하기~

목록 보기

2/3

코드 예시

/*
 * @(#)DiaryRepositoryCustom.java        1.0.9 2022/2/19
 *
 * Copyright (c) 2022 YoungJun Yang.
 * ComputerScience, ProgrammingLanguage, Java, Pocheon-si, KOREA
 * All rights reserved.
 */

package com.dasd412.remake.api.domain.diary.diabetesDiary;

import com.dasd412.remake.api.domain.diary.writer.Writer;
import com.querydsl.core.types.Predicate;

import java.util.List;
import java.util.Optional;

/**
 * 혈당일지 리포지토리 상위 인터페이스. Querydsl을 이용하기 위해 구현하였다.
 *
 * @author 양영준
 * @version 1.0.9 2022년 2월 19일
 */
public interface DiaryRepositoryCustom {

    /**
     * @return 식별자의 최댓값. 혈당 일지 생성 시 id를 지정하기 위해 사용된다. (복합키에는 @GeneratedValue 사용 불가.)
     */
    Long findMaxOfId();

    Optional<Writer> findWriterOfDiary(Long diaryId);

    List<DiabetesDiary> findDiabetesDiariesOfWriter(Long writerId);

    Optional<DiabetesDiary> findOneDiabetesDiaryByIdInWriter(Long writerId, Long diaryId);

    /**
     * @param writerId 작성자 id
     * @param diaryId  일지 id
     * @return 작성자가 작성한 혈당 일지 및 관련된 모든 엔티티
     */
    Optional<DiabetesDiary> findDiabetesDiaryOfWriterWithRelation(Long writerId, Long diaryId);

    /**
     * @param writerId   작성자 id
     * @param predicates where 절 조건문
     * @return 작성자가 작성했던 모든 혈당 일지와 관련된 모든 엔티티 "함께" 조회
     */
    List<DiabetesDiary> findDiabetesDiariesOfWriterWithRelation(Long writerId, List<Predicate> predicates);


    /**
     * @param writerID   작성자 id
     * @param predicates where 조건문
     * @return where 조건문에 맞는 일지들
     */
    List<DiabetesDiary> findDiariesWithWhereClause(Long writerID, List<Predicate> predicates);

    /**
     * 일지와 관련된 엔티티 (식단, 음식) 을 포함하여 "한꺼번에" 제거하는 메서드.
     *
     * @param diaryId 일지 Id
     */
    void bulkDeleteDiary(Long diaryId);

    /**
     * @param writerId   작성자 id
     * @param predicates where 조건
     * @return 전체 기간 공복혈당의 평균 값
     */
    Optional<Double> findAverageFpg(Long writerId, List<Predicate> predicates);

}

나쁜 주석 제거해보기

전반적으로 나쁜 주석이 많은 코드다. 참고로 글의 코드들은 2022년 12월 ~ 4월까지 개인적으로 작업했던 프로젝트의 일부다.

같은 이야기 중복

먼저, 같은 이야기를 중복하는 주석이 많다. Javadocs를 활용해서 주석을 많이 작성했는데, 오히려 정신이 없다.

코드 중 일부를 리팩토링한다면 다음과 같다.
이전 코드

    /**
     * @param writerId 작성자 id
     * @param diaryId  일지 id
     * @return 작성자가 작성한 혈당 일지 및 관련된 모든 엔티티
     */
    Optional<DiabetesDiary> findDiabetesDiaryOfWriterWithRelation(Long writerId, Long diaryId);

이후 코드

    Optional<DiabetesDiary> findDiabetesDiaryWithReleatedEntitiesOfWriter(Long writerId, Long diaryId);

@param같은 경우, 이미 변수 이름으로 충분히 설명이 된다. 따라서 사족으로 주석을 쓸 필요가 없다. @return 역시 함수 이름을 충분히 명료하게 작성하면 쓸 필요가 없어서 제거했다.
저자가 계속 말하듯이, 이름은 길더라도 의미만 명확하다면 짧고 명확하지 않은 코드보다 백배 낫다.

있으나 마나한 주석

/**
 * 혈당일지 리포지토리 상위 인터페이스. Querydsl을 이용하기 위해 구현하였다.
 *

너무 당연한 사실을 언급하고 있다. 제거.

공로를 돌리거나 저자를 표시하는 주석

/**
 * @author 양영준
 */

저자를 표시하는 주석은 Git이 있어서 표시할 필요가 1도 없다. 없앤다.

이력을 기록하는 주석

 *
 * @version 1.0.9 2022년 2월 19일
 */

이력을 기록하는 주석 역시 형상 관리 툴 Git이 생기고 나서 필요 없다. 따라서 제거한다.

의무적으로 다는 주석

모든 함수에 Javadocs를 달거나 모든 변수에 주석을 다는 것은 멍청한 짓이라고 한다. 위 코드의 경우 너무 많이 달려있어 한꺼번에 많이 제거해야 한다.

리팩토링

/*
 * @(#)DiaryRepositoryCustom.java
 *
 * Copyright (c) 2022 YoungJun Yang.
 * ComputerScience, ProgrammingLanguage, Java, Pocheon-si, KOREA
 * All rights reserved.
 */

package com.dasd412.remake.api.domain.diary.diabetesDiary;

import com.dasd412.remake.api.domain.diary.writer.Writer;
import com.querydsl.core.types.Predicate;

import java.util.List;
import java.util.Optional;

public interface DiaryRepositoryCustom {

    /**
     * @return 식별자의 최댓값. 혈당 일지 생성 시 id를 지정하기 위해 사용된다. (복합키에는 @GeneratedValue 사용 불가.)
     */
    Long findMaxOfId();

    Optional<Writer> findWriterOfDiary(Long diaryId);

    List<DiabetesDiary> findDiabetesDiariesOfWriter(Long writerId);

    Optional<DiabetesDiary> findOneDiabetesDiaryByIdInWriter(Long writerId, Long diaryId);

    Optional<DiabetesDiary> findDiabetesDiaryWithReleatedEntitiesOfWriter(Long writerId, Long diaryId);

    List<DiabetesDiary> findDiabetesDiariesWithReleatedEntitiesOfWriter(Long writerId, List<Predicate> predicates);

    List<DiabetesDiary> findDiariesWithWhereClause(Long writerID, List<Predicate> predicates);

    void bulkDeleteDiaryWithReleatedEntities(Long diaryId);

    Optional<Double> findAverageFpgWithWhereClause(Long writerId, List<Predicate> predicates);

}