Comment documentez-vous votre développement?

Question

Je construis ma première application complexe (dans RoR) et comme je pense à la transmettre à de nouveaux programmeurs, j'ai réfléchi aux meilleures façons de documenter ce que je construis.

Comment aimez-vous documenter votre travail?

Existe-t-il des logiciels ou des sites Web qui permettent d'accumuler facilement des sections de la documentation, peut-être avec un étiquetage pour faciliter la consultation ultérieure?

Answer 1

J'aime utiliser un wiki. Je pense qu'il rencontrerait tous les objectifs que vous avez cités:

• un moyen facile d'avoir différentes pages et sections
• recherche et d 'étiquetage est intégré généralement

De plus, il existe d'autres caractéristiques:

• Vous pouvez permettre aux autres d'aider à la documentation
• les documents peuvent se développer comme ils doivent: Commencez avec juste un sim un site d'une page. Ensuite, développez quand cela a du sens.

Mes deux favoris sont pbworks.com pour des projets privés: c'est gratuit pour certaines utilisations, et vous permet de définir des autorisations privées. Mon autre préféré est github, qui inclut un wiki avec chaque projet que vous créez.

Answer 2

J'ajoute beaucoup de commentaires; partout. J'ai pris le temps d'écrire ce qui se passe sous une forme lisible par l'homme pour chaque ligne de mon algorithme de génération musicale de 500 lignes, et cela m'a sauvé beaucoup de temps, ainsi que mes autres amis qui aidaient.

Voici ce que je l'ai fait (comme départ):

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 

Il est un début (et un exemple avec le code cruddy), mais il me aide du code de débogage vraiment rapidement.

Answer 3

Si je suis honnête: Je ne documente pas mes applications. Quand je reçois de nouveaux programmeurs dans mon équipe, je leur donne une introduction au domaine, et c'est tout. Ils peuvent lire les spécifications et les caractéristiques du concombre eux-mêmes. Si une configuration spéciale est requise, elle figure dans le fichier README. Ils peuvent aussi consulter la configuration CI.

C'est la puissance de la convention sur la configuration pour toi!

Answer 4

Que diriez-vous de rake doc:app avec le commentaire de code attendu?