4 ms·
Writing detailed commit notes can be useful in the same way. I have backed out of a commit during the write up more times than I would like to admit because I
by allannienhuis 10y ago
Writing detailed commit notes can be useful in the same way. I have backed out of a commit during the write up more times than I would like to admit because I realized that I hadn't covered some edge case or I completely forgot about something (like the effect of the change on a report or other sub-system). Writing things out in a way that someone else can understand forces you to re-think through the task in different ways.
- bhntr3 10y agoPeople sometimes tease me for reviewing my own pull requests. But I am a big believer in roles. The reviewer role is different than the creator role. When I mentally switch, through the priming mechanism of my code review tool, I am often able to see the defects in my own design or code. I sometimes do the same thing with design docs or proposals by imagining myself as the person who has the most to lose by my proposal succeeding and then commenting on my doc from their perspective.
- macintux 10y agoI've read that adding the "BUGS" section to man pages in the early days of UNIX had a similar impact. The developers got so embarrassed by the content that they decided to fix the bugs instead.
- Drdrdrq 10y agoIt is similar with the product we are developing. When I need to explain to the user how some feature is used, I often end up redesigning said feature so that explaining should not be needed. Makes for a much better UX. :)
- Drdrdrq 10y agoI try to explain my motivation behind change in commit log and avoid technical details myself. But I have another checkpoint. I always diff the code and review it as if I had to show it to a reviewer. If I need to explain something, it should be made better.