Source Code Wisdom
A summary of what I have learned, over the course of my career as a software developer, about managing and documenting source code.
Table of Contents
|
- Use a task manager to maintain high-level documentation of changes to the code.
- Use source control to maintain granular control over the code.
- Use the same or similar comments for a modification in the code, in source control and in the task manager.
- Peer review. All changes should be reviewed and tested by at least one other developer before formal QA.
In the Code
- Focus on readability. You shouldn't need comments to explain what the code does.
- Don't write what the unit of code does. What the code does should be evident from the code.
- Do explain anything that is not immediately evident from the code.
- Explain the why of the unit of code.
- Explain anything that goes against standard practice or convention.
- Be succinct.
- 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
- Have a "master" branch that contains the final, completely-tested, ready-for-primetime version of the code.
- Each branch that is not a trunk should correspond to exactly one task.
- Each task should have one final branch that is destined for production.
- 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
- Break code modifications into atomic units. Put each unit in a separate commit.
- Comment every commit indicating how/why the commit changes the code.
In the Task Manager
For Each Task
- Document which branches are associated with the particular task and which branch is the final branch.
- Include a test plan for the task.
- Include queries and commands that were executed in the process of completing the task.
- 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.)