Re: [PATCH/RFC] gitweb: Great subroutines renaming

From: Junio C Hamano <junkio@cox.net>
Date: Aug 7, 2006, 19:37 UTC
Message-ID: <7v3bc82v7l.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <200608071626.52655.jnareb@gmail.com>

Jakub Narebski <jnareb@gmail.com> writes:

> This RFC is about better naming of subroutines in gitweb. The patch was
> generated on top of 'next' (7c7e45d0cc0f482aeb19ecb0b56e9e7b65472c56)
> using embedded gitweb-rename.sh script.

Show 7 quoted lines

> Subroutines name guideline:
> * git_ prefix for subroutines related to git commands,
>   or to gitweb actions
> * git_get_ prefix for subroutines calling git command
>   and returning some output
> * git_read_ prefix for subroutines directly accessing git
>   repository files

 - (I am not complaining or objecting yet -- this is just an
   observation. ) The distinction between git_get_foo and
   git_read_foo is an implementation detail.  The latter could
   signal that the implementation bypasses the published
   interface but depends on the implementation detail of the
   low-level git, so it might be a good idea, but on the other
   hand the only instance is git_read_info_refs which reads from
   .git/info/refs -- and its format is part of the published
   interface -- so I am not so sure this distinction is worth
   it.  And certainly we would not want to rely too heavily on
   the current implementation of the low-level git, so we
   obviously do not want to add more git_read_foo's needlessly,
   which makes me feel even less sure if we would want
   git_read_foo...

Show 10 quoted lines

> * parse_ prefix for subroutines parsing some text, or reading and
>   parsing some text into hash or list
> * format_ prefix for subroutines formatting/post-processing some
>   HTML/text fragment
> * _get_ infix for subroutines which return result
> * _print_ infix for subroutines which print fragment of output
> * _body suffix for subroutines which outputs main part (body)
>   of related action
> * _nav suffix for subroutines related to navigation bars
> * _div suffix for subroutines returning or ptinting div element

 - All of these sound sane.

> How should subroutines be named? Do you agree with proposal, or not?

I suspect that the list may disagree with some minor details on the naming guidelines but I hope that everybody would in principle be in favor of this.

> Is such renaming usefull?

If we are to have many more fixes and clean-ups on gitweb, readable and consistent names would be very helpful.

The problem is when. If we are going to apply this, we need to pick a point of time when not many patches on gitweb are in flight; otherwise I'd end up asking people to resend using new names.