4 ms·

No. People don't read commit logs for fun. They read them to try to find the source of a bug or who changed a line last and what they thought they were doing.

by cjensen 14y ago

No. People don't read commit logs for fun. They read them to try to find the source of a bug or who changed a line last and what they thought they were doing. This breaks that functionality in two ways: 1. Recognizing the joke takes attention, which therefore means I have less attention available to track the thing I'm really hunting. The thing I'm hunting may take a lot of "state info" in my brain so I need that concentration. A commit log of "fix typo" can be quickly ignored without interrupting my brain state. 2. The commit log is not self-explainatory. You have to look at the diff to understand the joke. The whole point of a commit log is to summarize the change so I don't need to look at the diffs unless the commit is related to the functionality I'm investigating. "Fix typo" followed by the joke would have been acceptable.

deleted 14y ago
[deleted]
skyebook 14y ago
Couldn't agree more. I'll also be the first to admit though that some commit messages I've sent off after particularly infuriating bugs have had language that my mother would slap me for (and not very helpful, to boot). We're only human
sophacles 14y ago
Sometime's I feel like I'm the only person who understands code. Seriously, I don't look at comments, api docs, or commit logs unless I am unsure what the diff or code is telling me. I mean, joking with something this trivial is not really a big deal. There is no hidden motivation to change it, no hard to follow changes, no clever bits of code that are subtly altered. An output string is now without a typo. Big whoop. The only complaint that makes sense is "it's not that funny".
- qeorge 14y ago
  I hate this attitude. Really do. Its a cancer. You're not "the only person who understands code", you're the person who refuses to write good documentation based on a misplaced sense of superiority. Get over yourself.
  - jsight 14y ago
    Hate? Cancer? These words are a bit strong, eh? Have you read the original article? It was a minor correction to a typo in some documentation. I'm pretty sure everyone who knows how to read English would have understood the diff without reading any comments. The amusing comment was no big deal in this case, IMO. Situations differ. Absolute rules for all circumstances are far more of a cancer than a little levity.
  - sophacles 14y ago
    You've seen my pull requests then? When I write code for work or anyone but me I make sure it's well done. Just because I don't like it doesn't mean I don't do it. E.g.: https://github.com/marionettejs/backbone.marionette/pull/346 https://github.com/marionettejs/backbone.marionette/pull/346 for my most recent. So quit with the negative bullshit attitude and realize that you haven't a clue about what you're saying. Also note it isn't superior nothing. I'm just genuinely baffled that people are so hesitant about looking at code for a solution. No mater how good the dox I don't understand til I've read the code. Also note how in my linked example residing the docs was way less useful than just looking at the code. Not because the marionette ppl are the evil dancer you whine about but because they are ppl and sometimes things slip
    - jeremysmyth 14y ago
      > I'm just genuinely baffled that people are so hesitant about looking at code for a solution. No mater how good the dox I don't understand til I've read the code. Let me help. The code you look at to find the solution might be one 20 or 30 line chunk of Ruby that performs a service for a chunk of 10 year old VB or 20 year old Perl or 30 year old C, or some chain of several languages. A support guy, or apps-level documenter, or maintenance programmer adding a feature, or architect integrating with another system, or business integration consultant helping to decide where the business needs to invest, or some other decision maker really, really doesn't have time to read through 40,000 lines of code in several languages to find out how a feature works. For example: one of my first jobs was with an established big brand with many years of legacy data and organic "enterprise" systems, integrating data produced by an AS400 green-screen application into VB (on a Windows box) by copying (via FTP on a SCO box) a fixed-width text file produced by a shell script on the AS400, and parsing it so we could put it into Oracle for processing by a C++ application with API hooks into a Nortel Meridian coms system. When an outbound call goes to the wrong number, where's the bug? Even if I'm reading _my own_ code 6 or 36 months later, I'm much happier if I've logged the checkins correctly so that it narrows it down to which dozen or so of many thousands of commits touched a feature. Whenever I've had to track down someone else's bug, or tried to justify the technical justification for some business decision the system makes, or tried to write high level progress documentation (think changelog for senior managers), the commit messages make the difference between it taking two weeks and taking two years (i.e. never happening). It's easy to think, in the post-codial glow when you're fresh from the zone, that there's no way this code isn't absolutely obvious. I've been that guy. I've also been the guy that cursed that guy for making it hard to find the needle in the haystack. I've even been both guys separated by 18 months. Commit messages can make the difference between getting it done in 20 minutes, and "looking at code for a solution" for two days. I hope you're less baffled now :)
- james-skemp 14y ago
  Sure, that's fine, but how do you know what code to look at? For me, I want messages that are searchable so I know where I need to look within the mass of files. Then I can read the code just fine.
  - sophacles 14y ago
    I agree with that. Even more, I think all the documentation people should start being chastised for not providing a decent picture of two. I am a picture thinker, and code translates well to and from pictures for me. Not so much with the documentation. By analogy: I'm sure I could get an understanding of a city with written instructions on geting from various parts to other various parts. I'd do better just wandering around. However give me a map and I know it well pretty quick, especially if I can wander around with the map. Likewise with code, give me a single decent architecture or dataflow diagram and you've helped me more than a whole well written book about the codebase.

by cjensen 14y ago

deleted 14y ago

[deleted]

skyebook 14y ago

Couldn't agree more. I'll also be the first to admit though that some commit messages I've sent off after particularly infuriating bugs have had language that my mother would slap me for (and not very helpful, to boot). We're only human

sophacles 14y ago

Sometime's I feel like I'm the only person who understands code. Seriously, I don't look at comments, api docs, or commit logs unless I am unsure what the diff or code is telling me. I mean, joking with something this trivial is not really a big deal. There is no hidden motivation to change it, no hard to follow changes, no clever bits of code that are subtly altered. An output string is now without a typo. Big whoop. The only complaint that makes sense is "it's not that funny".

qeorge 14y ago
I hate this attitude. Really do. Its a cancer. You're not "the only person who understands code", you're the person who refuses to write good documentation based on a misplaced sense of superiority. Get over yourself.
- jsight 14y ago
  Hate? Cancer? These words are a bit strong, eh? Have you read the original article? It was a minor correction to a typo in some documentation. I'm pretty sure everyone who knows how to read English would have understood the diff without reading any comments. The amusing comment was no big deal in this case, IMO. Situations differ. Absolute rules for all circumstances are far more of a cancer than a little levity.
- sophacles 14y ago
  You've seen my pull requests then? When I write code for work or anyone but me I make sure it's well done. Just because I don't like it doesn't mean I don't do it. E.g.: https://github.com/marionettejs/backbone.marionette/pull/346 https://github.com/marionettejs/backbone.marionette/pull/346 for my most recent. So quit with the negative bullshit attitude and realize that you haven't a clue about what you're saying. Also note it isn't superior nothing. I'm just genuinely baffled that people are so hesitant about looking at code for a solution. No mater how good the dox I don't understand til I've read the code. Also note how in my linked example residing the docs was way less useful than just looking at the code. Not because the marionette ppl are the evil dancer you whine about but because they are ppl and sometimes things slip
  - jeremysmyth 14y ago
    > I'm just genuinely baffled that people are so hesitant about looking at code for a solution. No mater how good the dox I don't understand til I've read the code. Let me help. The code you look at to find the solution might be one 20 or 30 line chunk of Ruby that performs a service for a chunk of 10 year old VB or 20 year old Perl or 30 year old C, or some chain of several languages. A support guy, or apps-level documenter, or maintenance programmer adding a feature, or architect integrating with another system, or business integration consultant helping to decide where the business needs to invest, or some other decision maker really, really doesn't have time to read through 40,000 lines of code in several languages to find out how a feature works. For example: one of my first jobs was with an established big brand with many years of legacy data and organic "enterprise" systems, integrating data produced by an AS400 green-screen application into VB (on a Windows box) by copying (via FTP on a SCO box) a fixed-width text file produced by a shell script on the AS400, and parsing it so we could put it into Oracle for processing by a C++ application with API hooks into a Nortel Meridian coms system. When an outbound call goes to the wrong number, where's the bug? Even if I'm reading _my own_ code 6 or 36 months later, I'm much happier if I've logged the checkins correctly so that it narrows it down to which dozen or so of many thousands of commits touched a feature. Whenever I've had to track down someone else's bug, or tried to justify the technical justification for some business decision the system makes, or tried to write high level progress documentation (think changelog for senior managers), the commit messages make the difference between it taking two weeks and taking two years (i.e. never happening). It's easy to think, in the post-codial glow when you're fresh from the zone, that there's no way this code isn't absolutely obvious. I've been that guy. I've also been the guy that cursed that guy for making it hard to find the needle in the haystack. I've even been both guys separated by 18 months. Commit messages can make the difference between getting it done in 20 minutes, and "looking at code for a solution" for two days. I hope you're less baffled now :)
james-skemp 14y ago
Sure, that's fine, but how do you know what code to look at? For me, I want messages that are searchable so I know where I need to look within the mass of files. Then I can read the code just fine.
- sophacles 14y ago
  I agree with that. Even more, I think all the documentation people should start being chastised for not providing a decent picture of two. I am a picture thinker, and code translates well to and from pictures for me. Not so much with the documentation. By analogy: I'm sure I could get an understanding of a city with written instructions on geting from various parts to other various parts. I'd do better just wandering around. However give me a map and I know it well pretty quick, especially if I can wander around with the map. Likewise with code, give me a single decent architecture or dataflow diagram and you've helped me more than a whole well written book about the codebase.