top | item 32903496

(no title)

r24y | 3 years ago

One thing that I believe is under-documented in code is _business decisions_. The team arrives at a decision in a meeting or informal discussion, and it leads to some code that might be tough to understand without context. I'll usually add a comment briefly describing the decision, and initial and date it.

Initially I would just link to a wiki page in a comment, but occasionally these links break, so in my experience it's better to include the notes directly.

discuss

order

Archelaos|3 years ago

It is often also useful not only to document the decision the team arrives at, but also briefly write down what was decided not to implement and why. This is very helpful when people come in a few weeks later with a "new" idea that has already been discussed, or in onboarding new people to the project.

tcoff91|3 years ago

The commit message should contain all the unusual context needed to understand the change. In practice however, most people write terrible commit messages.

bornfreddy|3 years ago

It's not just that. Commit messages have a property that they get overwritten. When I refactor some code for performance reasons, I don't want to remove documentation - which is exactly what happens if I make a commit. True, older commit messages are available in the history, but... not conveniently available.

ParetoOptimal|3 years ago

Many never even use multi-line commit messages.

conradfr|3 years ago

And ideally the id of the ticket associated to the code change.