[matlab] 함수 주석 작성 방법

4433 단어 matlab

동기 부여



matlab을 사용하여 10년 정도가 되었는데, 함수 코멘트를 어떻게 써야할지, 아직도 고민하기 때문에 다시 정리한다.

함수 주석 작성 방법



기본은 mathworks 프로그램에 도움말 추가를 따릅니다.
  • 첫 번째 줄에 함수 이름 (왜 대문자)과 개요 작성
  • 2행째 이후에 사용법을 쓴다. 인수 생략이 가능한 경우는 생략한 형태도 쓴다.
  • 중간에 인수와 반환 값에 대한 정보를 씁니다 (이것은 나의 규칙입니다.
  • 마지막 행과 관련된 프로그램에 대한 정보 작성

    함수 주석의 예



    간단한 선형 탐색 프로그램에 주석을 주었다.

    linear_search.m
    function is_match = linear_search(key, input_nums)
    %LINEAR_SEARCH 線形探索
    %
    % is_match = linear_search(key, input_nums)
    %  
    % Parameters
    % ----------
    % key : numeric
    %   検索する数
    % input_nums : vector(numeric)
    %   検索対象である数値配列
    % 
    % Returns
    % -------
    % is_match : vector(bool)
    %   一致していればtrue,それ以外ならfalseを格納
    %
    % see also: find
    
    % 引数チェック
    validateattributes(key,{'numeric'},{'scalar'})
    validateattributes(input_nums,{'numeric'},{'vector'})
    
    % 格納先準備
    N = length(input_nums);
    is_match = false(N, 1);
    
    % 線形探索
    for index = 1:length(input_nums)
        if(key == input_nums(index))
            is_match(index) = true;
        end
    end
    
    end
    

    명령 창에서 doc linear_search로 설정하면 다음과 같은 화면이 나타납니다.

    help linear_search 그러면 명령 창에 도움말이 출력됩니다 (출력 결과 생략).

    matlab 함수의 인수 및 반환 값 정보



    matlab은 유형을 정의하지 않으므로 가능한 경우 함수 주석에 인수와 반환 값에 대한 정보를 작성해야합니다. 특히 matlab은 아카데믹한 사용자가 많기 때문에, 괜찮아 Nalpha와 같은 심플한 변수명이 나옵니다.

    그렇다면 함수 코멘트 내에서 어떻게 써야 하는가 하면 특히 이런 스타일은 Matlab 업계에 없는 것 같습니다. 그래서 위의 샘플에서는 파이썬의 numpy 스타일을 참고로 설명했습니다. numpy 스타일 이외에도 google 스타일 등이 있으므로 이들을 참고에 쓰는 방법을 결정합시다.

    또, 형을 어떻게 써야 하는가, 라고 하는 문제도 있습니다만, 나는 validateattributes 과 맞춘 쓰는 방법이 좋다고 생각합니다. 위의 샘플에서는 함수의 시작 부분에서 인수의 keynumericscalar인지 확인합니다. validateattributes 는 매우 유연하고, 정수나 정수 등, 알고리즘 조작으로 자주 등장하는 조건도 체크할 수 있으므로, 적극적으로 사용해 갑시다.
  • 좋은 웹페이지 즐겨찾기