How do you document your development? [closed]

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 5 years ago.

开发者_如何学JAVA Improve this question

I am building my first complex app (in RoR) and as I think about passing it on to new programmers, I have been thinking about the best ways to document what I'm building.

How do you like to document your work?

Are there softwares or websites that allow one to easily accumulate sections of documentation, perhaps with tagging for easy reference later on?

---

If I'm honost: I don't document my apps. When I get new programmers on my team, I give them an introduction to the domain, and that's it. They can read the specs and cucumber features themselves. If there is any special setup required, it's in the README. They can check out the CI configuration too.

That's the power of convention over configuration for ya!

---

I like to use a wiki. I think it would meet all the goals you named:

• an easy way to have various pages and sections
• searching and tagging is usually built-in

Plus, there are other features:

• You can allow others to help out with the documentation
• The docs can grow as they need to: Start out with just a simple one-page site. Then expand when it makes sense.

My two favorites are pbworks.com for private projects: it's free for some uses, and lets you set permissions to private. My other favorite is github, which includes a wiki with every project you create.

---

I add lots of comments; everywhere. I took the time to write out what logic is happening in human-readable form for every single line of my 500 line music-generation algorithm, and it saved me so much time, and my other friends who were helping.

Here's what I did (as a start):

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

It's a start (and an example with cruddy code), but it helps me debug code really quickly.

---

How about rake doc:app along with expected code commenting?