개발 문서화 방법은 무엇입니까?

Question

(RoR에서) 첫 번째 복잡한 앱을 만들고 있는데, 새로운 프로그래머에게 전달하는 것에 대해 생각하면서 건물을 문서화하는 최선의 방법을 생각해 보았습니다.

작품을 어떻게 문서화 하시겠습니까?

쉽게 참조 할 수 있도록 태그가 달린 문서 섹션을 쉽게 누적 할 수있는 소프트웨어 또는 웹 사이트가 있습니까?

Answer 1

위키를 사용하고 싶습니다.

• 다양한 페이지와 섹션
• 검색 및 태그 일반적으로 내장되어

플러스가하는 쉬운 방법은, 다른 기능이 있습니다 : 나는 당신이라는 이름의 모든 목표를 달성 할 것이라고 생각 :

당신은 다른 사람들이 필요로

워드 프로세서가 성장할 수있는 문서에 도움을 허용 할 수 있습니다

: 단지 시뮬레이션으로 시작 한 페이지에 불과합니다. 그런 다음 확장하십시오.

두 가지 즐겨 찾기는 비공개 프로젝트 용으로 pbworks.com입니다. 일부 용도에는 무료이며 비공개로 사용 권한을 설정할 수 있습니다. 내가 좋아하는 다른 곳은 당신이 만드는 모든 프로젝트가 들어있는 위키가 포함 된 github입니다.

Answer 2

많은 의견을 추가합니다. 어디에나. 나는 나의 500 라인 뮤직 생성 알고리즘의 모든 단일 라인에 대해 인간이 읽을 수있는 형태로 어떤 논리가 일어나고 있는지 알려주며, 많은 시간과 도움을 주던 다른 친구들을 구해 주었다.

def __init__(self): 
    self.chromatic = ['C', ['C#', 'Db'], 'D', ['D#', 'Eb'], 'E', 'F', ['F#', 'Gb'], 'G', ['G#', 'Ab'], 'A', ['A#', 'Bb'], 'B'] 

    self.steps = {} 
    self.steps['major']     = [2, 2, 1, 2, 2, 2, 1] 
    self.steps['natural minor']   = [2, 1, 2, 2, 1, 2, 2] 
    self.steps['harmonic minor']  = [2, 1, 2, 2, 1, 3] 
    self.steps['melodic minor up']  = [2, 1, 2, 2, 2, 2, 1] 
    self.steps['melodic minor down'] = [2, 2, 1, 2, 2, 1, 2] 
    self.steps['dorian']    = [2, 1, 2, 2, 2, 1, 2] 
    self.steps['mixolydian']   = [2, 2, 1, 2, 2, 1, 2] 
    self.steps['ahava raba']   = [1, 3, 1, 2, 1, 2, 2] 
    self.steps['minor penatonic blues'] = [3, 2, 2, 3, 2] 

    self.list = [] 

def scale(self, note, name):       # Function to generate a scale from the required base note. 
    if re.sub('[^0-9]', '', note) == '':    # Checks for nonexistent octave number 
    octave = 5          # Defaults to 5 
    else:            # If octave number exists 
    octave = int(re.sub('[^0-9]', '', note))   # Extracts octave number from note 

    note = re.sub('[0-9]', '', note)     # Strips all numbers from note 
    scale = []           # Initializes the scale to be empty 

    for i in rlen(self.chromatic):      # Loops through all elements of the Chromatic scale 
    if self.chromatic[i] is not list:     # If the note is just a natural 
     if note == self.chromatic[i]: scale = [i + 1] # Check if the note is in the chromatic. If it is, add it. 
    else: 
     if note in self.chromatic[i]: scale = [i + 1] # If the note is in a key of the chromatic, add it too. It is a sharp/flat. 

    for i in rlen(self.steps[name]):     # Loops through desired scale 
    scale.append(self.steps[name][i] + scale[i])  # Adds string notes following the algorithm of the scale 
    scale[i + 1] = scale[i + 1] % len(self.chromatic) # Modulo length of Chromatic scale 

그것은 시작 (및 cruddy 코드 예를 들어), 그러나 그것은 빨리 저에게 정말 코드를 디버깅 하는 데 도움이 :

는 여기에 내가 (시작으로) 무슨 짓을했는지.

Answer 3

내가 정직한 경우 : 내 앱을 문서화하지 않았습니다. 팀에 새로운 프로그래머가 생겼을 때 도메인에 대한 소개를하고, 그게 전부입니다. 그들은 사양과 오이 기능을 읽을 수 있습니다. 특별한 설정이 필요한 경우 README에 있습니다. 그들은 CI 구성도 체크 아웃 할 수 있습니다.

그 이상의 구성에 대한 관례입니다.

Answer 4

약 rake doc:app와 함께 예상되는 코드 주석이 있습니까?