댓글을 잘 활용하는 방법

이것은 종종 초보자에게 비판적인 것이지만 초보자이든 아니든 모든 사람이 알고 있으며 많은 개발자가 자신의 코드에 대해 달리 나쁘게 언급하지 않습니다.

⚠️ 기술 및 비즈니스에 대한 내 블로그 게시물on my personal blog을 더 읽어보세요! ⚠️

코드를 변경하고 주석을 달기 위해 여기에 있다고 가정합니다. 양질의 댓글은 어떻게 작성하나요?

댓글에 대한 DRY

댓글을 작성하는 것은 이미 그다지 재미있는 일이 아니므로 너무 많이 작성하거나 여러 곳에 동일한 정보를 작성하지 마십시오.

지나치게 주석이 달린 코드(특히 주석에서 자신을 반복하는 경우)는 주석이 없는 코드만큼 나쁘다고 스스로에게 말하십시오. 실제로, 그것은 빠르게 불쾌감을 줄 것이고 아무도 당신의 댓글을 읽지 않을 것이므로 완전히 쓸모 없게 됩니다.

주석에서 자신을 반복하지 않고 더 효율적으로 만드는 기술은 코드의 위치에 따라 특정 주석에 대한 특정 정보를 예약하는 것입니다.

4개의 위치 = 4가지 댓글 유형

의견 제출

이 설명은 파일의 나이, 작성자 및 기타 필요한 파일 수준 정보를 나타내는 데 유용합니다.

/*
 * Converter.swift
 * EuroConverter
 *
 * Created by Nathanaël Cherrier on 19/06/2016.
 * Copyright © 2016 Nathanaël Cherrier. All rights reserved.
 */

class Converter: NSObject {
    private var _base: String!

    init(base: String = "EUR") throws {
        super.init()

        try validateCurrency(base)
        _base = base

        getExchangeRatesFor(base)
    }
}

일부 IDE는 이러한 파일 주석의 생성 및 수정을 자동화합니다. 이 경우 날짜, 기여자 이름 및 파일 이름은 필요에 따라 변경됩니다.

수업 댓글

클래스 댓글은 클래스에 대한 정보(용도, 버전, 호환성 등)를 수집합니다.

/*
 * Allows you to convert currencies
 * 
 * @class Converter
 * @since 3.1
 */
class Converter: NSObject {
    private var _base: String!

    init(base: String = "EUR") throws {
        super.init()

        try validateCurrency(base)
        _base = base

        getExchangeRatesFor(base)
    }
}

메서드 및 함수 설명

이것들은 확실히 당신이 가장 많은 것을 쓸 댓글입니다. 이를 통해 클래스를 사용하는 모든 개발자는 메서드 코드를 보지 않고도 클래스를 사용하는 방법을 이해할 수 있습니다.

분석법 주석이 잘 작성되어 있으면 귀중한 시간을 절약해 준 것에 대해 동료들이 고마워할 것입니다.

class Converter: NSObject {
    private var _base: String!

    /*
     * Initializes the class with a primary currency
     * @param base {String} Currency used as the basis for the rates 
     * (pairs base/USD, base/EUR, etc.) 
     *
     * @throws {ValidationError} Error if wrong currency 
     * is given in parameters.
     * @return {void}
     */
    init(base: String = "EUR") throws {
        super.init()

        try validateCurrency(base)
        _base = base

        getExchangeRatesFor(base)
    }
}

정밀 코멘트

이 댓글은 마지막 수준입니다. 복잡한 코드 블록 또는 특정 선택 사항(방법론, 디자인…)을 설명하기 위해 코드 중간에 작성됩니다.

class Converter: NSObject {
    private var _base: String!

    init(base: String = "EUR") throws {
        super.init()

        // We don't catch the error here 
        // We leave the management to the user of the class
        try validateCurrency(base) 
        _base = base

        getExchangeRatesFor(base)
    }
}