tag:blogger.com,1999:blog-7214366369588984730.post4340212720867323321..comments2024-02-23T21:44:21.191-08:00Comments on Insufficiently Random: Why commit messages matterShawnhttp://www.blogger.com/profile/04158038862839573213noreply@blogger.comBlogger5125tag:blogger.com,1999:blog-7214366369588984730.post-89070924167967141872010-02-04T06:35:05.000-08:002010-02-04T06:35:05.000-08:00Thanks for the post, I pointed some 2nd year CS st...Thanks for the post, I pointed some 2nd year CS students at it to explain why high quality commit messages are important. (It is at times horrifying to see the quality of the commit messages by 1st and 2nd year CS students.) Hopefully this'll motivate them to Do The Right Thing (TM) from now on ;).Sverre Rabbelierhttp://code.google.com/p/socnoreply@blogger.comtag:blogger.com,1999:blog-7214366369588984730.post-88268389134493650222010-02-04T10:58:47.000-08:002010-02-04T10:58:47.000-08:00I agree that the information you know when you cod...I agree that the information you know when you code, especially the "why" need to be written down.<br>Code written over a year ago is as obscure as if it were written by someone else. However, I think<br>that the information you know ought to be provided as literate programming (ref: Knuth) rather than<br>in changelogs. That is, the "how" and "why" information needs to be in paragraphs of text that <br>reside in the source code, next to the code that implements the ideas. Having the information stored<br>in changelogs implies that I know what to look for and by that time I'm already deep into debugging.<br>The information in a literate source file format is available when I start looking at the code.Tim Dalyhttp://daly.axiom-developer.orgnoreply@blogger.comtag:blogger.com,1999:blog-7214366369588984730.post-6573316664977508232010-02-20T10:15:55.000-08:002010-02-20T10:15:55.000-08:00I think you should take a look at git's git re...I think you should take a look at git's git respository to better understand the advantage of commit messages over inline comments. The git repository has approximately 250 thousand lines of code and only about 20 thousand lines of comments. But it has 200 thousand lines of commit messages. Having such a detailed history is incredibly useful.<br><br>Commit messages are more powerful than inline code comments for several reasons.<br><br>- They are associated with a single logical change, which has a very specific motivation to comment on. This is useful if you want to know why a problem was solved in a particular way. If you read the code, however, you do not usually want to know "why was this implemented like this, and not like that." First, you want to know what the code does and how it works. Having inline explanations for the motivation behind writing the code would only be a distraction at that point.<br><br>- Inline comments are often misleading, because they are not maintained with the code. It is hard to keep all comments up-to-date, because you have to notice that a certain comment pertains to a change you made and is possibly invalidated by it.<br><br>- Commit messages, on the other hand, maintain themselves, because they belong to a version and can therefore be associated with a change. If code that you commented on in a commit message is changed later, the commit message will automatically be updated with the new change. And you are still able to dig out the original commit that created the code.<br><br>The event that the repository is not available to view the commit message information is quite unlikely, especially because git by default copies all history information locally. If you're going to read the code without its history, you might as well read it without syntax highlighting, ctags or grep.Clemens Buchachernoreply@blogger.comtag:blogger.com,1999:blog-7214366369588984730.post-85824632763421390082010-02-04T22:50:32.000-08:002010-02-04T22:50:32.000-08:00Nothing against the point you make here, but the p...Nothing against the point you make here, but the pathetic lack of comments in the choose_repository.tcl source file prompts me to say this: Such explanations belong in the source file, not in the meta information of a possibly inaccessible repository. I absolutely second Tim Daly's point.Leonoreply@blogger.comtag:blogger.com,1999:blog-7214366369588984730.post-26543863020549093642010-02-04T21:26:44.000-08:002010-02-04T21:26:44.000-08:00Yes, this kind of information should be in comment...Yes, this kind of information should be in comments, not commit messages.Sveger Olofsonnoreply@blogger.com