3 ms·
i agree in general. i've only got ~15 years of professional experience, but: - code says how it's done - comments say why it's done - comments say why someth
by baq 6y ago
i agree in general. i've only got ~15 years of professional experience, but:
- code says how it's done
- comments say why it's done
- comments say why something isn't done
- comments say how to use the damn thing
- comments say who thought it was a good idea to implement the damn thing
- answers to above questions are usually provided in code review as replies and actually should be comments in code
- mikeyjk 6y agoAgree except for the 'who', that sounds like it should be in the work tracking system (e.g. JIRA) rather than comments in code.
- baq 6y agobut then, see the point about work tracking systems being outside of source history and thus prone to migration failures, etc. also, git blame sort of fills this role, but the commit author may not be the person who acked the implementation and requires digging in history if there were any refactorings done.
- rags2riches 6y agoI'd expand the first item to NAMES say how it's done. Need it to be clearer? Add more intermediate vars and functions with good informative names.