A summary of what I have learned, over the course of my career as a software developer, about managing and documenting source code.

  1. Use a task manager to maintain high-level documentation of changes to the code.
  2. Use source control to maintain granular control over the code.
  3. Use the same or similar comments for a modification in the code, in source control and in the task manager.
  4. Peer review. All changes should be reviewed and tested by at least one other developer before formal QA.

In the Code

  1. Focus on readability. You shouldn't need comments to explain what the code does.
  2. Don't write what the unit of code does. What the code does should be evident from the code.
  3. Do explain anything that is not immediately evident from the code.
  4. Explain the why of the unit of code.
  5. Explain anything that goes against standard practice or convention.
  6. Be succinct.
  7. Tag modifications with external identifiers.
    • Preferably the number of the task or work order that the modification accomplishes.
    • If not, username or initials of developer and date of modification.
    • Exception: Redundant information that can be obtained from source control or the task manager.

In the Source Control

Branches

  1. Have a "master" branch that contains the final, completely-tested, ready-for-primetime version of the code.
  2. Each branch that is not a trunk should correspond to exactly one task.
  3. Each task should have one final branch that is destined for production.
  4. Not every branch will ultimately go into production. It is quite alright to have branches that exist to try different approaches to solving a task.

Commits

  1. Break code modifications into atomic units. Put each unit in a separate commit.
  2. Comment every commit indicating how/why the commit changes the code.

In the Task Manager

For Each Task

  1. Document which branches are associated with the particular task and which branch is the final branch.
  2. Include a test plan for the task.
  3. Include queries and commands that were executed in the process of completing the task.
  4. Tag or categorize notes to indicate attributes such as:
    • Scope (technical, management, etc.)
    • Purpose (requirement, guidance, test plan, etc.)
    • Audience (developer, project manager, supervisor, etc.)