3 ms·
IME (20 years in web-related software dev / arch / mgmt), the best ROI in this area comes from two things: - good commit messages - references to persistent r
by chrisweekly 8y ago
IME (20 years in web-related software dev / arch / mgmt), the best ROI in this area comes from two things:
- good commit messages
- references to persistent requirements artifacts (eg Trello cards, Jira tickets, whatever)
YMMV... but really doing these two things makes a huge difference.
- thaumaturgy 8y agoBoth of your examples require the developer to access some resource outside of the code itself in order to understand what the code is doing (or why it is doing it). So those things are both good also, but I consider them to be a fallback for cases where the code isn't commented like it should be.
- chrisweekly 8y agoComments can provide context by simply providing a link like "See Issue/ticket/card ID #123". That plus git blame, good commit messages, and feature branches named for the same ID, makes for a coherent whole -- without adding much overhead in terms of comment writing and maintenance.