{"thread":{"id":"10865","subject":"[PATCH] Add line-wrapping guidelines to the coding style documentation","startedAt":"2007-11-14T10:19:05Z","lastAt":"2007-11-14T20:23:49Z","messageCount":7,"participants":["Wincent Colaiuta","Junio C Hamano","Johannes Schindelin","Andreas Ericsson"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"59842","messageId":"56A87A65-3C2E-4E10-84D4-4470879EE466@wincent.com","threadId":"10865","inReplyTo":null,"subject":"[PATCH] Add line-wrapping guidelines to the coding style documentation","fromName":"Wincent Colaiuta","fromEmail":"win@wincent.com","sentAt":"2007-11-14T10:19:05Z","receivedAt":"2007-11-14T10:19:05Z","isPatch":true,"sender":{"key":"greg@hurrell.net","avatar":"https://avatars.githubusercontent.com/u/7074?v=4"},"body":"Help new contributors by providing some advice about line-wrapping; the\nadvice basically boils down to \"use 80-characters minus some slop as a\nrule of thumb\", but also \"use common sense\", and \"avoid gratuitous\nrewrapping\".\n\nSigned-off-by: Wincent Colaiuta <win@wincent.com>\n---\n\nThe advice is based on the following post by Junio:\n\nEl 14/11/2007, a las 10:27, Junio C Hamano escribió:\n\n> I did not mean to say 70 was the official limit.  Indeed, there\n> is no hard official limit (and there shouldn't be any \"hard\"\n> limit).  But 70 should certainly be lower than the limit anybody\n> around here would want to impose, and that was why I said 70.\n>\n> Some considerations:\n>\n> - Many of us read the unformatted ASCII version, as AsciiDoc\n>   was designed to be very readable, and mixing excessively long\n>   and short lines will make the document harder to read.\n>\n> - We tend to exchange patches over e-mail and assume everybody\n>   has at least 80-column wide terminals, so although we say a\n>   line should be less than 80-chars, in practice the limit is\n>   somewhat lower. to accomodate diff change marks [-+ ] and\n>   quoting \">> \" in e-mails.\n>\n> - But \"80-chars minus a bit of slop\" is not a very hard limit.\n>\n> Please apply some common sense to decide when to re-wrap and\n> when not to within these constraints.\n\n\nI also whipped up this quick Ruby script to print a histogram of line  \nwidths in the tree. You would run it like this to get a feel for the  \ntypical line lengths of the different types of file in the tree:\n\ncheck-column-widths.rb *.c *.h\ncheck-column-widths.rb *.sh\ncheck-column-widths.rb *.perl\ncheck-column-widths.rb Documentation/*.txt\n\nA statistician could probably make some interesting comments about the  \nresults, but the basic trend is that, while there are plenty of  \nexamples of isolated long lines in the source tree (the longest is a  \n287-character line in one of the perl scripts), the frequency starts  \nto drop off pretty rapidly once you pass 70 columns and start climbing  \ntowards 80.\n\n#!/usr/bin/env ruby\n\nextensions = {}\n\n# count frequency of line widths\nARGV.each do |arg|\n   f = File.new arg\n   extname = File.extname arg\n   unless file_type = extensions[extname]\n     extensions[extname] = file_type = {}\n   end\n   f.readlines.each do |line|\n     len = line.chomp.length\n     count = (file_type[len] or 0)\n     file_type[len] = count + 1\n   end\nend\n\n# print results\nextensions.each do |file_type, frequencies|\n   puts \"Frequencies for #{file_type} files\"\n\n   # find longest line, most frequent line width, total line count\n   longest       = frequencies.max { |a, b| a[0] <=> b[0] }[0]\n   most_frequent = frequencies.max { |a, b| a[1] <=> b[1] }[1]\n   total_lines   = frequencies.inject(0) { |sum, a| sum + a[1] }\n\n   # draw histogram\n   for i in 0..longest\n     next if frequencies[i].nil?\n     puts \"%4d [%4d]: %s\" % [i, frequencies[i], '.' * (frequencies[i]  \n* 60 / most_frequent)]\n   end\n   puts \"Maximum length: #{longest}\"\n   puts \"   Total lines: #{total_lines}\"\nend\n\n  Documentation/CodingGuidelines |   22 ++++++++++++++++++++++\n  1 files changed, 22 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/ \nCodingGuidelines\nindex 3b042db..3fd698e 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -110,3 +110,25 @@ For C programs:\n     used in the git core command set (unless your command is clearly\n     separate from it, such as an importer to convert random-scm-X\n     repositories to git).\n+\n+Line wrapping:\n+\n+ - While there are no official hard limits for line wrapping, we\n+   generally try to keep shell scripts, C source files and AsciiDoc\n+   documentation within the range of \"80-characters minus some\n+   slop\".\n+\n+ - We assume that everyone has terminals that are at least 80\n+   columns wide.\n+\n+ - In practice, we try to keep lines somewhat narrower than 80\n+   columns to accommodate diff change marks [-+ ] and quoting \">> \"\n+   in emails.\n+\n+ - In the case of documentation, mixing excessively long and short\n+   lines may make the AsciiDoc source harder to read, so try to\n+   keep line lengths consistent.\n+\n+ - When submitting patches use common sense to decide whether to\n+   rewrap, avoiding gratuitous changes.\n+\n-- \n1.5.3.5\n"},{"id":"59843","messageId":"7vsl39i041.fsf@gitster.siamese.dyndns.org","threadId":"10865","inReplyTo":"56A87A65-3C2E-4E10-84D4-4470879EE466@wincent.com","subject":"Re: [PATCH] Add line-wrapping guidelines to the coding style documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-11-14T10:37:34Z","receivedAt":"2007-11-14T10:37:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Wincent Colaiuta <win@wincent.com> writes:\n\n> A statistician could probably make some interesting comments about the  \n> results, but the basic trend is that, while there are plenty of  \n> examples of isolated long lines in the source tree (the longest is a  \n> 287-character line in one of the perl scripts), the frequency starts  \n> to drop off pretty rapidly once you pass 70 columns and start climbing  \n> towards 80.\n\nGaah.  287???\n\n> + - In the case of documentation, mixing excessively long and short\n> +   lines may make the AsciiDoc source harder to read, so try to\n> +   keep line lengths consistent.\n> +\n> + - When submitting patches use common sense to decide whether to\n> +   rewrap, avoiding gratuitous changes.\n\nHmph.  The last item applies only to the documentation because\nit uses the word \"rewrap\", but otherwise applies equally well to\nthe sources (re-indenting).  So probably \"whether to rewrap or\nreindent\" would be a good change there.\n"},{"id":"59855","messageId":"Pine.LNX.4.64.0711141717570.4362@racer.site","threadId":"10865","inReplyTo":"56A87A65-3C2E-4E10-84D4-4470879EE466@wincent.com","subject":"Re: [PATCH] Add line-wrapping guidelines to the coding style documentation","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-11-14T17:19:27Z","receivedAt":"2007-11-14T17:19:27Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Wed, 14 Nov 2007, Wincent Colaiuta wrote:\n\n> Help new contributors by providing some advice about line-wrapping; the \n> advice basically boils down to \"use 80-characters minus some slop as a \n> rule of thumb\", but also \"use common sense\", and \"avoid gratuitous \n> rewrapping\".\n\nWe already have this:\n\n - We try to keep to at most 80 characters per line.\n\nBesides, is it really necessary to be as explicit as you word it?  IOW is \nthis patch needed?\n\nBecause if we go down that road, we might very well end up with a \nCodingGuidelines document that is larger than git's source code.\n\nCiao,\nDscho\n"},{"id":"59861","messageId":"622166FD-0727-47D4-B26C-8A01788FD1EA@wincent.com","threadId":"10865","inReplyTo":"Pine.LNX.4.64.0711141717570.4362@racer.site","subject":"[PATCH v3] Add line-wrapping guidelines to the coding style documentation","fromName":"Wincent Colaiuta","fromEmail":"win@wincent.com","sentAt":"2007-11-14T19:00:45Z","receivedAt":"2007-11-14T19:00:45Z","isPatch":true,"sender":{"key":"greg@hurrell.net","avatar":"https://avatars.githubusercontent.com/u/7074?v=4"},"body":"Help new contributors by providing some advice about line-wrapping; the\nadvice basically boils down to \"use 80 columns minus some slop as a\nrule of thumb\", but also \"use common sense\", and \"avoid gratuitous\nrewrapping\".\n\nSigned-off-by: Wincent Colaiuta <win@wincent.com>\n---\n\nEl 14/11/2007, a las 18:19, Johannes Schindelin escribió:\n\n> On Wed, 14 Nov 2007, Wincent Colaiuta wrote:\n>\n>> Help new contributors by providing some advice about line-wrapping;  \n>> the\n>> advice basically boils down to \"use 80-characters minus some slop  \n>> as a\n>> rule of thumb\", but also \"use common sense\", and \"avoid gratuitous\n>> rewrapping\".\n>\n> We already have this:\n>\n> - We try to keep to at most 80 characters per line.\n\nAh, didn't see that. It's in the \"C programs\" section and I was trying  \nto provide a guideline that applied to all source types (given that  \nthis all started with a doc patch to an AsciiDoc source file).\n\n> Besides, is it really necessary to be as explicit as you word it?   \n> IOW is\n> this patch needed?\n\nI was basically just trying to help new people from making the same  \nmistake that I did; ie. not knowing if there was an official limit,  \nlooking at the maximum line length in a file, making sure my patch  \ndidn't exceed that length (and re-wrapping to avoid exceeding it), and  \nthen getting reprimanded for gratuitous re-wrapping.\n\nAs for the explicitness, I was just paraphrasing the guidelines as  \nJunio expressed them.\n\n> Because if we go down that road, we might very well end up with a\n> CodingGuidelines document that is larger than git's source code.\n\n134 lines down (the current length of CodingGuidelines with that  \npatch), about 100,000 lines to go (the rest of the codebase). So if we  \ntry very hard, we could indeed get there.\n\nHere follows a revised patch which is more concise, and keeps all  \nwrapping references at a single place. I lose your \"at most 80  \ncharacters\" in favor of Junio's \"80-characters minus some slop\", and  \nin fact state \"80 columns\" rather than \"80 characters\", because that's  \nwhat we're really talking about, isn't it?\n\nCheers,\nWincent\n\n  Documentation/CodingGuidelines |   13 +++++++++++--\n  1 files changed, 11 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/ \nCodingGuidelines\nindex 3b042db..d2d1f32 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -58,8 +58,6 @@ For C programs:\n   - We use tabs to indent, and interpret tabs as taking up to\n     8 spaces.\n\n- - We try to keep to at most 80 characters per line.\n-\n   - When declaring pointers, the star sides with the variable\n     name, i.e. \"char *string\", not \"char* string\" or\n     \"char * string\".  This makes it easier to understand code\n@@ -110,3 +108,14 @@ For C programs:\n     used in the git core command set (unless your command is clearly\n     separate from it, such as an importer to convert random-scm-X\n     repositories to git).\n+\n+Line wrapping:\n+\n+ - We generally try to keep scripts, C source files and AsciiDoc\n+   documentation within the range of \"80 columns minus some slop\"\n+   to accommodate diff change marks [-+ ] and quoting \">> \" in\n+   emails.\n+\n+ - When submitting patches use common sense to decide whether to\n+   rewrap (or reindent), avoiding gratuitous changes.\n+\n-- \n1.5.3.5\n"},{"id":"59862","messageId":"473B47C0.6030508@op5.se","threadId":"10865","inReplyTo":"622166FD-0727-47D4-B26C-8A01788FD1EA@wincent.com","subject":"Re: [PATCH v3] Add line-wrapping guidelines to the coding style documentation","fromName":"Andreas Ericsson","fromEmail":"ae@op5.se","sentAt":"2007-11-14T19:08:48Z","receivedAt":"2007-11-14T19:08:48Z","isPatch":true,"sender":{"key":"ae@op5.se","avatar":"https://gravatar.com/avatar/426e89595c75a8f5252dd0c989e5fabe5bcac616e68557427ad9aef6b0ca342a?d=mp&s=160"},"body":"Wincent Colaiuta wrote:\n> Help new contributors by providing some advice about line-wrapping; the\n> advice basically boils down to \"use 80 columns minus some slop as a\n> rule of thumb\", but also \"use common sense\", and \"avoid gratuitous\n> rewrapping\".\n> \n> Signed-off-by: Wincent Colaiuta <win@wincent.com>\n> ---\n> \n> El 14/11/2007, a las 18:19, Johannes Schindelin escribió:\n> \n>> On Wed, 14 Nov 2007, Wincent Colaiuta wrote:\n>>\n>>> Help new contributors by providing some advice about line-wrapping; the\n>>> advice basically boils down to \"use 80-characters minus some slop as a\n>>> rule of thumb\", but also \"use common sense\", and \"avoid gratuitous\n>>> rewrapping\".\n>>\n>> We already have this:\n>>\n>> - We try to keep to at most 80 characters per line.\n> \n> Ah, didn't see that. It's in the \"C programs\" section and I was trying \n> to provide a guideline that applied to all source types (given that this \n> all started with a doc patch to an AsciiDoc source file).\n> \n>> Besides, is it really necessary to be as explicit as you word it?  IOW is\n>> this patch needed?\n> \n> I was basically just trying to help new people from making the same \n> mistake that I did; ie. not knowing if there was an official limit, \n> looking at the maximum line length in a file, making sure my patch \n> didn't exceed that length (and re-wrapping to avoid exceeding it), and \n> then getting reprimanded for gratuitous re-wrapping.\n> \n> As for the explicitness, I was just paraphrasing the guidelines as Junio \n> expressed them.\n> \n>> Because if we go down that road, we might very well end up with a\n>> CodingGuidelines document that is larger than git's source code.\n> \n> 134 lines down (the current length of CodingGuidelines with that patch), \n> about 100,000 lines to go (the rest of the codebase). So if we try very \n> hard, we could indeed get there.\n> \n> Here follows a revised patch which is more concise, and keeps all \n> wrapping references at a single place. I lose your \"at most 80 \n> characters\" in favor of Junio's \"80-characters minus some slop\", and in \n> fact state \"80 columns\" rather than \"80 characters\", because that's what \n> we're really talking about, isn't it?\n> \n> Cheers,\n> Wincent\n> \n>  Documentation/CodingGuidelines |   13 +++++++++++--\n>  1 files changed, 11 insertions(+), 2 deletions(-)\n> \n> diff --git a/Documentation/CodingGuidelines \n> b/Documentation/CodingGuidelines\n> index 3b042db..d2d1f32 100644\n> --- a/Documentation/CodingGuidelines\n> +++ b/Documentation/CodingGuidelines\n> @@ -58,8 +58,6 @@ For C programs:\n>   - We use tabs to indent, and interpret tabs as taking up to\n>     8 spaces.\n> \n> - - We try to keep to at most 80 characters per line.\n> -\n>   - When declaring pointers, the star sides with the variable\n>     name, i.e. \"char *string\", not \"char* string\" or\n>     \"char * string\".  This makes it easier to understand code\n> @@ -110,3 +108,14 @@ For C programs:\n>     used in the git core command set (unless your command is clearly\n>     separate from it, such as an importer to convert random-scm-X\n>     repositories to git).\n> +\n> +Line wrapping:\n> +\n> + - We generally try to keep scripts, C source files and AsciiDoc\n> +   documentation\n\n\"We generally try to keep source and documentation\" ... ?\n\n-- \nAndreas Ericsson                   andreas.ericsson@op5.se\nOP5 AB                             www.op5.se\nTel: +46 8-230225                  Fax: +46 8-230231\n"},{"id":"59867","messageId":"7v4pfoh9vu.fsf@gitster.siamese.dyndns.org","threadId":"10865","inReplyTo":"622166FD-0727-47D4-B26C-8A01788FD1EA@wincent.com","subject":"Re: [PATCH v3] Add line-wrapping guidelines to the coding style documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-11-14T20:04:05Z","receivedAt":"2007-11-14T20:04:05Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Wincent Colaiuta <win@wincent.com> writes:\n\n> El 14/11/2007, a las 18:19, Johannes Schindelin escribió:\n>\n>> Besides, is it really necessary to be as explicit as you word it?\n>> IOW is\n>> this patch needed?\n>\n> I was basically just trying to help new people from making the same\n> mistake that I did; ie. not knowing if there was an official limit,\n> looking at the maximum line length in a file, making sure my patch\n> didn't exceed that length (and re-wrapping to avoid exceeding it), and\n> then getting reprimanded for gratuitous re-wrapping.\n\nSorry about that \"reprimanded\" part.  I should have been more\ncareful -- I did not really mean it that way.  It was more like\n\"it would have been nicer ... so please try to next time\".\n\nI know how stressful a life is for a contributor new to a\nproject.  You not only need to make sure the meat of your change\nis good, but worry about the technicalities, such as the\npresentation and style, the tone of the proposed log message\nthat addresses other peoples efforts you are building on; in\nshort, finding out the lay of the land, making yourself blend\nwell in the comminity.\n\nWe have a great way to quickly tell if somebody is new to the\nproject (i.e. \"git shortlog --author=Wincent master\").  I should\nuse it more often and adjust my tone accordingly.  It's only\nfair for me to do so when the new person surely is trying hard\nto do his part.\n\n> diff --git a/Documentation/CodingGuidelines b/Documentation/\n> CodingGuidelines\n> index 3b042db..d2d1f32 100644\n> --- a/Documentation/CodingGuidelines\n> +++ b/Documentation/CodingGuidelines\n> @@ -58,8 +58,6 @@ For C programs:\n>   - We use tabs to indent, and interpret tabs as taking up to\n>     8 spaces.\n>\n> - - We try to keep to at most 80 characters per line.\n> -\n>   - When declaring pointers, the star sides with the variable\n>     name, i.e. \"char *string\", not \"char* string\" or\n>     \"char * string\".  This makes it easier to understand code\n\nI agree that \"80 columns\" sits better in that new \"Line\nwrapping\" section.  I wonder if \"tabs are 8 spaces wide\" also\nbelong there.\n\n> @@ -110,3 +108,14 @@ For C programs:\n>     used in the git core command set (unless your command is clearly\n>     separate from it, such as an importer to convert random-scm-X\n>     repositories to git).\n> +\n> +Line wrapping:\n> +\n> + - We generally try to keep scripts, C source files and AsciiDoc\n> +   documentation within the range of \"80 columns minus some slop\"\n> +   to accommodate diff change marks [-+ ] and quoting \">> \" in\n> +   emails.\n> +\n> + - When submitting patches use common sense to decide whether to\n> +   rewrap (or reindent), avoiding gratuitous changes.\n> +\n"},{"id":"59871","messageId":"8515B0B6-9C28-41F1-B197-3EF821D43590@wincent.com","threadId":"10865","inReplyTo":"7v4pfoh9vu.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH v3] Add line-wrapping guidelines to the coding style documentation","fromName":"Wincent Colaiuta","fromEmail":"win@wincent.com","sentAt":"2007-11-14T20:23:49Z","receivedAt":"2007-11-14T20:23:49Z","isPatch":true,"sender":{"key":"greg@hurrell.net","avatar":"https://avatars.githubusercontent.com/u/7074?v=4"},"body":"El 14/11/2007, a las 21:04, Junio C Hamano escribió:\n\n> Wincent Colaiuta <win@wincent.com> writes:\n>\n>> El 14/11/2007, a las 18:19, Johannes Schindelin escribió:\n>>\n>>> Besides, is it really necessary to be as explicit as you word it?\n>>> IOW is\n>>> this patch needed?\n>>\n>> I was basically just trying to help new people from making the same\n>> mistake that I did; ie. not knowing if there was an official limit,\n>> looking at the maximum line length in a file, making sure my patch\n>> didn't exceed that length (and re-wrapping to avoid exceeding it),  \n>> and\n>> then getting reprimanded for gratuitous re-wrapping.\n>\n> Sorry about that \"reprimanded\" part.  I should have been more\n> careful -- I did not really mean it that way.  It was more like\n> \"it would have been nicer ... so please try to next time\".\n\nDon't worry about it, Junio. I've been subscribed to the list for  \nseveral months now, so I'm already aware of the perfectionism inherent  \nin the process; I didn't take anything personally, and much less  \ncoming from you who is always diplomatic. I just thought, \"this is  \ngood advice that Junio has posted to the list, I found it helpful, so  \nI think it should go in the style doc\".\n\nAnd I'm no stranger to Johannes' scything sarcasm either, it's his  \npersonal style; luckily, along with the sarcasm he makes so many high- \nquality contributions to the community as well.\n\n> I agree that \"80 columns\" sits better in that new \"Line\n> wrapping\" section.  I wonder if \"tabs are 8 spaces wide\" also\n> belong there.\n\nYou're probably right; I understand that the 8-wide tabs convention  \nholds in shell and perl scripts too, not just in C source.\n\nCheers,\nWincent\n"}]}