git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Eric Sunshine <sunshine@sunshineco.com>
To: Emily Shaffer <emilyshaffer@google.com>
Cc: Git List <git@vger.kernel.org>
Subject: Re: [PATCH] documentation: add tutorial for revision walking
Date: Sun, 23 Jun 2019 14:54:59 -0400	[thread overview]
Message-ID: <CAPig+cTCfm3wi2G6q1ZW9wVwQB9zp0TQ96BXKKt8E+qxfR-UWA@mail.gmail.com> (raw)
In-Reply-To: <20190619233556.GH100487@google.com>

On Wed, Jun 19, 2019 at 7:36 PM Emily Shaffer <emilyshaffer@google.com> wrote:
> On Wed, Jun 19, 2019 at 04:13:35AM -0400, Eric Sunshine wrote:
> > Maybe I got confused because the tiny cmd_walken() snippets followed
> > one another so closely (or because I got interrupted several times
> > during the review), but one way to avoid that would be to present a
> > single _complete_ snippet from the start, followed by a bit of
> > explanation. [...]
>
> Hmm. I can say that I personally would find that much more difficult to
> follow interactively, and I'd be tempted to copy-and-paste and skim
> through the wall of text if I was presented with such a snippet.
> However, I could also imagine the reverse - someone becoming tired of
> having their hand held through a fairly straightforward implementation,
> when they're perfectly capable of reading a long description and would
> just like to get on with it.
>
> (Maybe we can split the difference and present a complete patch or new
> function, followed by a breakdown? That would end up even more verbose
> than the current approach, though.)

It might not be that important and may not need fixing considering
that I read it correctly the second time, and don't know how I managed
to get confused on the first read.

> > As this is just a toy example, I don't care too strongly about the
> > unnecessary second sentence. On the other hand, the tutorial is trying
> > to teach people how to contribute to this project, and on this
> > project, that sort of pointless comment is likely to be called out in
> > review. In fact, given that view, the entire comment block is
> > unnecessary (it doesn't add any value for anyone reviewing or reading
> > the code), so it might make more sense to drop the comment from the
> > code entirely, and just do a better job explaining in prose above the
> > snippet why you are calling that function. For instance:
> >
> >     ... Let's start the helper with the call to `prepare_revision_walk()`,
> >     which does the final setup of the `rev_info` structure before it can
> >     be used.
> >
> > The above observation may be more widely applicable than to just this
> > one instance. Don't use in-code comments for what should be explained
> > in prose if the in-code comment adds no value to the code itself (to
> > wit, if a reviewer would say "don't repeat in a comment what the code
> > already says clearly" or "don't use a comment to state the obvious").
>
> I'm of two minds about this. On the one hand, I'm somewhat in favor of
> leaving contextual, informational comments in the sample code, so the
> sample code can teach on its own without the tutorial (specifically, I
> mean the patchset that was sent alongside this one as RFC). On the other
> hand, you're right that adding these informational comments doesn't
> model best practices for real commits.
>
> I don't have a strong opposition to removing those comments from the
> in-place samples in the tutorial itself. But I do think it's useful to
> include them in the sample patchset, which is intended as an additional
> learning tool, rather than as a pristine code example - especially if we
> make it clear in the commit messages there.

Indeed, having the comments in the sample patch-set makes sense for
people who learn better that way (by seeing a complete piece of code).

> > > > Or make the output more useful by having it be machine-parseable (and
> > > > not localized):
> > > >
> > > >     printf("commits %d\nblobs %d\ntags %d\ntrees %d\n",
> > > >         commit_count, blob_count, tag_cont, tree_count);
> > >
> > > I'm not sure whether I agree, since it's a useless toy command only for human
> > > parsing.
> >
> > True, it's not a big deal, and I don't insist upon it. But, if you
> > mention in prose that this output is easily machine-parseable, then
> > perhaps that nudges the reader a bit in the direction of thinking
> > about porcelain vs. plumbing, which is something a contributor to this
> > project eventually has to be concerned with (the sooner, the better).
>
> Oh, that's a very good point. I'll frame it that way - that's a handy
> place to slip in some bonus context about Git. Thanks.
>
>   NOTE: We aren't localizing the printf here because we have purposefully
>   formatted it in a machine-parseable way. Commands in Git are divided into
>   "plumbing" and "porcelain"; the "plumbing" commands are machine-parseable and
>   intended for use in scripts, while the "porcelain" commands are intended for
>   human interaction. Output intended for script usage doesn't need to be
>   localized; output intended for humans does.

I'd go with stronger language than "doesn't need to be localized" and
say instead that plumbing output "must not be localized" since scripts
depend upon stable output (and stable API).

  reply	other threads:[~2019-06-23 18:55 UTC|newest]

Thread overview: 102+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-06-07  1:07 [PATCH] documentation: add tutorial for revision walking Emily Shaffer
2019-06-07  1:07 ` [RFC PATCH 00/13] example implementation of revwalk tutorial Emily Shaffer
2019-06-07  1:07   ` [RFC PATCH 01/13] walken: add infrastructure for revwalk demo Emily Shaffer
2019-06-07  1:08   ` [RFC PATCH 02/13] walken: add usage to enable -h Emily Shaffer
2019-06-07  1:08   ` [RFC PATCH 03/13] walken: add placeholder to initialize defaults Emily Shaffer
2019-06-07  1:08   ` [RFC PATCH 04/13] walken: add handler to git_config Emily Shaffer
2019-06-07  1:08   ` [RFC PATCH 05/13] walken: configure rev_info and prepare for walk Emily Shaffer
2019-06-07  1:08   ` [RFC PATCH 06/13] walken: perform our basic revision walk Emily Shaffer
2019-06-07  1:08   ` [RFC PATCH 07/13] walken: filter for authors from gmail address Emily Shaffer
2019-06-07  1:08   ` [RFC PATCH 08/13] walken: demonstrate various topographical sorts Emily Shaffer
2019-06-07  1:08   ` [RFC PATCH 09/13] walken: demonstrate reversing a revision walk list Emily Shaffer
2019-06-07  1:08   ` [RFC PATCH 10/13] walken: add unfiltered object walk from HEAD Emily Shaffer
2019-06-07  1:08   ` [RFC PATCH 11/13] walken: add filtered object walk Emily Shaffer
2019-06-07 19:15     ` Jeff Hostetler
2019-06-17 20:30       ` Emily Shaffer
2019-06-07  1:08   ` [RFC PATCH 12/13] walken: count omitted objects Emily Shaffer
2019-06-07  1:08   ` [RFC PATCH 13/13] walken: reverse the object walk order Emily Shaffer
2019-06-07  6:21 ` [PATCH] documentation: add tutorial for revision walking Eric Sunshine
2019-06-10 21:26   ` Junio C Hamano
2019-06-10 21:38     ` Eric Sunshine
2019-06-17 23:19   ` Emily Shaffer
2019-06-19  8:13     ` Eric Sunshine
2019-06-19 23:35       ` Emily Shaffer
2019-06-23 18:54         ` Eric Sunshine [this message]
2019-06-10 20:25 ` Junio C Hamano
2019-06-17 23:50   ` Emily Shaffer
2019-06-19 15:17     ` Junio C Hamano
2019-06-20 21:06       ` Emily Shaffer
2019-07-13  0:39         ` Josh Steadmon
2019-07-16  0:06           ` Emily Shaffer
2019-07-16 17:24             ` Junio C Hamano
2019-06-10 20:49 ` Junio C Hamano
2019-06-17 23:33   ` Emily Shaffer
2019-06-26 23:49 ` [PATCH v2] " Emily Shaffer
2019-06-26 23:50   ` [RFC PATCH v2 00/13] example implementation of revwalk tutorial Emily Shaffer
2019-06-26 23:50     ` [RFC PATCH v2 01/13] walken: add infrastructure for revwalk demo Emily Shaffer
2019-06-26 23:50     ` [RFC PATCH v2 02/13] walken: add usage to enable -h Emily Shaffer
2019-06-27  4:47       ` Eric Sunshine
2019-06-27 18:40         ` Emily Shaffer
2019-06-27  4:50       ` Eric Sunshine
2019-06-26 23:50     ` [RFC PATCH v2 03/13] walken: add placeholder to initialize defaults Emily Shaffer
2019-06-26 23:50     ` [RFC PATCH v2 04/13] walken: add handler to git_config Emily Shaffer
2019-06-27  4:54       ` Eric Sunshine
2019-06-27 18:47         ` Emily Shaffer
2019-06-26 23:50     ` [RFC PATCH v2 05/13] walken: configure rev_info and prepare for walk Emily Shaffer
2019-06-27  5:06       ` Eric Sunshine
2019-06-27 18:56         ` Emily Shaffer
2019-06-26 23:50     ` [RFC PATCH v2 06/13] walken: perform our basic revision walk Emily Shaffer
2019-06-27  5:16       ` Eric Sunshine
2019-06-27 20:54         ` Emily Shaffer
2019-06-26 23:50     ` [RFC PATCH v2 07/13] walken: filter for authors from gmail address Emily Shaffer
2019-06-27  5:20       ` Eric Sunshine
2019-06-27 20:58         ` Emily Shaffer
2019-06-26 23:50     ` [RFC PATCH v2 08/13] walken: demonstrate various topographical sorts Emily Shaffer
2019-06-27  5:22       ` Eric Sunshine
2019-06-27 22:12         ` Emily Shaffer
2019-06-26 23:50     ` [RFC PATCH v2 09/13] walken: demonstrate reversing a revision walk list Emily Shaffer
2019-06-27  5:26       ` Eric Sunshine
2019-06-27 22:20         ` Emily Shaffer
2019-06-26 23:50     ` [RFC PATCH v2 10/13] walken: add unfiltered object walk from HEAD Emily Shaffer
2019-06-27  5:37       ` Eric Sunshine
2019-06-27 22:31         ` Emily Shaffer
2019-06-28  0:48           ` Eric Sunshine
2019-07-01 19:19             ` Emily Shaffer
2019-06-26 23:50     ` [RFC PATCH v2 11/13] walken: add filtered object walk Emily Shaffer
2019-06-27  5:42       ` Eric Sunshine
2019-06-27 22:33         ` Emily Shaffer
2019-06-26 23:50     ` [RFC PATCH v2 12/13] walken: count omitted objects Emily Shaffer
2019-06-27  5:44       ` Eric Sunshine
2019-06-26 23:50     ` [RFC PATCH v2 13/13] walken: reverse the object walk order Emily Shaffer
2019-06-27 22:56     ` [RFC PATCH v2 00/13] example implementation of revwalk tutorial Emily Shaffer
2019-07-01 20:19   ` [PATCH v3] documentation: add tutorial for revision walking Emily Shaffer
2019-07-01 20:20     ` [RFC PATCH v3 00/13] example implementation of revwalk tutorial Emily Shaffer
2019-07-01 20:20       ` [RFC PATCH v3 01/13] walken: add infrastructure for revwalk demo Emily Shaffer
2019-07-01 20:20       ` [RFC PATCH v3 02/13] walken: add usage to enable -h Emily Shaffer
2019-07-01 20:20       ` [RFC PATCH v3 03/13] walken: add placeholder to initialize defaults Emily Shaffer
2019-07-01 20:20       ` [RFC PATCH v3 04/13] walken: add handler to git_config Emily Shaffer
2019-07-01 20:20       ` [RFC PATCH v3 05/13] walken: configure rev_info and prepare for walk Emily Shaffer
2019-07-01 20:20       ` [RFC PATCH v3 06/13] walken: perform our basic revision walk Emily Shaffer
2019-07-01 20:20       ` [RFC PATCH v3 07/13] walken: filter for authors from gmail address Emily Shaffer
2019-07-01 20:20       ` [RFC PATCH v3 08/13] walken: demonstrate various topographical sorts Emily Shaffer
2019-07-01 20:20       ` [RFC PATCH v3 09/13] walken: demonstrate reversing a revision walk list Emily Shaffer
2019-07-01 20:20       ` [RFC PATCH v3 10/13] walken: add unfiltered object walk from HEAD Emily Shaffer
2019-07-01 20:20       ` [RFC PATCH v3 11/13] walken: add filtered object walk Emily Shaffer
2019-07-01 20:20       ` [RFC PATCH v3 12/13] walken: count omitted objects Emily Shaffer
2019-07-01 20:20       ` [RFC PATCH v3 13/13] walken: reverse the object walk order Emily Shaffer
2019-07-25  9:25       ` [RFC PATCH v3 00/13] example implementation of revwalk tutorial Johannes Schindelin
2019-08-06 23:13         ` Emily Shaffer
2019-08-08 19:19           ` Johannes Schindelin
2019-07-24 23:11     ` [PATCH v3] documentation: add tutorial for revision walking Josh Steadmon
2019-07-24 23:32     ` Jonathan Tan
2019-08-06 23:10       ` Emily Shaffer
2019-08-06 23:19     ` [PATCH v4] " Emily Shaffer
2019-08-07 19:19       ` Junio C Hamano
2019-08-14 18:33         ` Emily Shaffer
2019-08-14 19:18           ` Junio C Hamano
2019-10-10 15:19       ` [PATCH v5] documentation: add tutorial for object walking Emily Shaffer
2019-10-11  5:50         ` Junio C Hamano
2019-10-11 23:26           ` Emily Shaffer
2019-10-11 17:50         ` SZEDER Gábor
2019-10-11 23:33           ` Emily Shaffer
2019-10-11 23:55         ` [PATCH v6] " Emily Shaffer

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=CAPig+cTCfm3wi2G6q1ZW9wVwQB9zp0TQ96BXKKt8E+qxfR-UWA@mail.gmail.com \
    --to=sunshine@sunshineco.com \
    --cc=emilyshaffer@google.com \
    --cc=git@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).