2 ms·
This. Also, commit messages are sometimes the "documentation of last resort". In my organization, putting comments in the code is frowned upon. "Comments are
by brian_cunnie 7y ago
This.
Also, commit messages are sometimes the "documentation of last resort".
In my organization, putting comments in the code is frowned upon. "Comments are lies! The documentation is in the tests!"
But the tests don't lend themselves to _reasons_ behind why the code was written a certain way, why a given approach was taken (for example, we needed to re-write a Rails database migration in a somewhat contorted manner to avoid a deadlock that was occurring in production).
In such organizations, the git commit message are often the best place to warn future programmers of pitfalls: "don't even think of parallelizing these table updates—you'll get deadlocks!"
[edited for brevity]
- brigandish 7y agoThe why is the thing most often missing from documentation of any sort. I often find myself looking at the README for a library I've not heard of and wondering what it will do for me because it only states the what, the why often tells me the/a problem the library solves. > Foobar packs JSON into binary vs > Our Rest API was slow and bandwidth heavy, so we wrote a library (Foobar) that packs JSON into a binary format. Now our messages are 50% smaller and 30% faster. Git commit messages are worse offenders but there's plenty of criminals about!