Code Archaeology - NAVADMC/ADSM GitHub Wiki

Your primary source of information should always be the code itself. I try to use long descriptive names so that the code is as readable as possible. The long term problem with Documentation and inline comments is that they can become out of sync with the state of the code. It will be the maintainers responsibility to update Documentation whenever a commit changes something mentioned in the Docs.

The GitHub Issues are a vast historical resource for ADSM. Use git blame to identify when code changed and trace that back to the issue, and discussion that created that change. This gives you access to a temporal record of line by line code that inline comments simply cannot match. In order for this to continue to be an effective tool you must follow GitHub Etiquette.

GitHub Etiquette

• Informative commit messages should be complete sentences listing the important parts that changed.
• Include Issue numbers (e.g. #236) in all of your commits. It's a rare commit that isn't for an Issue
• Make Issues for everything: discussions, bugs, planned feature, meeting notes that actually result in action items.
• Reference related commit numbers e.g. "Related to #37, depdends on #211" in your issue descriptions. GitHub will create backtrack links as well. It's very nice.
• Close your Issues from a commit message. If you need an explanatory paragraph at the end, leave a comment on the Issue as well. This is necessary about 1/5 of the time. Commit messages are really designed to be one line sentences.

If you do all these things, every line of code links to a commit, which links to an issue, which contains a discussion of what is changing and why, which links to a series of commits, which show you the total diff of code that had to change to make that happen. It's like having a photographic memory that you can share. Because git history is so informative, I recommend using an IDE like PyCharm that can "Show Git History for Selection" in your code.