Re: [PATCH v2] Add a comment to .clang-format about the meaning of the file

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 1, 2017, 20:30 UTC
Message-ID: <xmqq3772vce4.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20171001154425.5568-1-s-beyer@gmx.net>

Stephan Beyer <s-beyer@gmx.net> writes:

Show 21 quoted lines

> Having a .clang-format file in a project can be understood in a way that code
> has to be in the style defined by the .clang-format file, i.e., you just have
> to run clang-format over all code and you are set. This is not the case in the
> Git project, which is now reflected by a comment in the beginning of the file.
>
> Additionally, the working clang-format version is mentioned because the config
> directives change from time to time (in a compatibility-breaking way).
>
> Signed-off-by: Stephan Beyer <s-beyer@gmx.net>
> ---
>
> Notes:
>     On 10/01/2017 04:45 AM, Junio C Hamano wrote:
>     > it makes as if a random patch to "make it
>     > conform" without thinking if the rules make sense were a welcome
>     > addition, which is absolutely the last signal we would want to send
>     > to the readers.
>     
>     Right. I dropped that last sentence and replaced it by a sentence about human
>     aesthetics judgement overruling mechanical rules -- I think that's somehow quoted
>     from a comment of yours on the list.

Sorry, but that is not what I meant.

I think we do want the endgame to be that .clang-format defines how the code should look like. It's that we are not there yet, and I think that is what we should say in this comment.

	Note that this style definition does not yet quite reflect
	how we want our code to look like, and adjusting the rules
	to match our style is still work in progress.  Do not
	blindly adjust the style of _existing_ code, without
	checking if the code is styled incorrectly, or the style
	definition in this file is still wrong.

is what I should have suggested when writing my response.