3 ms·

So what you actually write is // We foobify the baz in order to ensure that both // sides of the transaction have their grinks froddled. // This wa

by gjm11 11y ago

So what you actually write is // We foobify the baz in order to ensure that both // sides of the transaction have their grinks froddled. // This was a request from Steve in Accounting; // see issue #4125 for more details. so that (1) if you'd otherwise be wondering "wait, what they hell are they doing that for?", you get an answer (and, importantly, some inkling of what would need to have changed for removing the code to be a good idea), (2) there's an indication of where you can find more details (hopefully including the original request from Steve in Accounting), and (3) if the code around here changes, you can still tell that the relevant bit is the foobification of the baz. I strongly approve of putting relevant info in your VCS commits too, of course. But, e.g., if someone changes the indentation around there then your git blame will show only the most recent change, which isn't the one you want, whereas the comment will hopefully survive intact.

ajuc 11y ago
Changed formatting isn't a problem IMHO. You can ask git to skip whitespace changes, and you can (and should) enforce consistent formatting anyway to make history cleaner. And even if for some reason you don't want to do either - you can just click "blame previous revision" if you do encounter "changed formatting" revision. I envountered it a few times and it was never a big problem. The problem with comments in the code is - they have to be maintained "by hand", and they are often separated from the context after a few independent changes. When you change a function called inside the foobify function because of another change request you will most probably forget to check all the calling places all the way up the callstack and fix the comments refering to foobify function. And then comments may start to lie. I encountered lying comments a few times and it usually is a big problem. I started to ignore comments when debugging, and I'm not the only programmer that I know that does that. I do think there is a place for comments in the code, for example for documentation of some API, but IMHO commit messages are the perfect place for explaining reasons of particular change, and I prefer not to repeat that. http://cdn.meme.am/instances2/500x/4310914.jpg http://cdn.meme.am/instances2/500x/4310914.jpg

by gjm11 11y ago

ajuc 11y ago

Changed formatting isn't a problem IMHO. You can ask git to skip whitespace changes, and you can (and should) enforce consistent formatting anyway to make history cleaner. And even if for some reason you don't want to do either - you can just click "blame previous revision" if you do encounter "changed formatting" revision. I envountered it a few times and it was never a big problem. The problem with comments in the code is - they have to be maintained "by hand", and they are often separated from the context after a few independent changes. When you change a function called inside the foobify function because of another change request you will most probably forget to check all the calling places all the way up the callstack and fix the comments refering to foobify function. And then comments may start to lie. I encountered lying comments a few times and it usually is a big problem. I started to ignore comments when debugging, and I'm not the only programmer that I know that does that. I do think there is a place for comments in the code, for example for documentation of some API, but IMHO commit messages are the perfect place for explaining reasons of particular change, and I prefer not to repeat that. http://cdn.meme.am/instances2/500x/4310914.jpg http://cdn.meme.am/instances2/500x/4310914.jpg