From owner-svn-src-head@FreeBSD.ORG Sun Jul 7 22:03:36 2013 Return-Path: Delivered-To: svn-src-head@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id DAF476FE; Sun, 7 Jul 2013 22:03:36 +0000 (UTC) (envelope-from avg@FreeBSD.org) Received: from citadel.icyb.net.ua (citadel.icyb.net.ua [212.40.38.140]) by mx1.freebsd.org (Postfix) with ESMTP id 1E95218BA; Sun, 7 Jul 2013 22:03:34 +0000 (UTC) Received: from porto.starpoint.kiev.ua (porto-e.starpoint.kiev.ua [212.40.38.100]) by citadel.icyb.net.ua (8.8.8p3/ICyb-2.3exp) with ESMTP id BAA27620; Mon, 08 Jul 2013 01:03:32 +0300 (EEST) (envelope-from avg@FreeBSD.org) Received: from localhost ([127.0.0.1]) by porto.starpoint.kiev.ua with esmtp (Exim 4.34 (FreeBSD)) id 1Uvx3M-0004Cz-D4; Mon, 08 Jul 2013 01:03:32 +0300 Message-ID: <51D9E57F.3090803@FreeBSD.org> Date: Mon, 08 Jul 2013 01:02:39 +0300 From: Andriy Gapon User-Agent: Mozilla/5.0 (X11; FreeBSD amd64; rv:17.0) Gecko/20130405 Thunderbird/17.0.5 MIME-Version: 1.0 To: Alfred Perlstein Subject: Re: svn commit: r253002 - head References: <201307072039.r67KdCdR028908@svn.freebsd.org> <9D4C7540-A3B0-45E5-8219-6A455D41DF70@gmail.com> <51D9DA55.2090808@freebsd.org> <51D9E069.5060300@FreeBSD.org> <51D9E2C0.6060603@freebsd.org> In-Reply-To: <51D9E2C0.6060603@freebsd.org> X-Enigmail-Version: 1.5.1 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Cc: "svn-src-head@freebsd.org" , "svn-src-all@freebsd.org" , "src-committers@freebsd.org" , Garrett Cooper X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 07 Jul 2013 22:03:36 -0000 on 08/07/2013 00:50 Alfred Perlstein said the following: > On 7/7/13 2:40 PM, Andriy Gapon wrote: >> on 08/07/2013 00:15 Alfred Perlstein said the following: >>> On 7/7/13 2:01 PM, Garrett Cooper wrote: >>>> Why the magic number 12? >>> Numbers higher seem to result in worse performance as reported by some members >>> of my team. >> Should we really commit all "notes to self" or "my team's knowledge base" to >> FreeBSD source code like this? > > I would hope so! I hope not ;) > At least in comments, that way we can all help each other. > > Otherwise each time another person comes along they are subject to having to > discover the same things that I did. > > What is the point of listing 10+ make targets if someone coming in doesn't know > which ones to run and how to run them optimally in order to ensure a safe > build? Do you not agree that more of this sort of documentation should be in > the code instead of having to ask on IRC? > > For the record I checked multiple pages in developer primer and scoured > makefiles for a while before giving up and asking on IRC. I figured it would be > helpful for the next clueless goon that came in and tried to make things better > if I recorded my experience to guide them. > > I hold no strong feelings towards the comments, other than they should be > preserved in some form, or maybe even turned into a workable target for people > that don't want or can not hold all that context in their brains. I am sure that the next time you need to run the same thing you'll remember where you put the comment and you'll copy/paste from it. I am sure that if any other developer runs into the same situation, then he will: - google - ask on irc - ask on mailing lists - perhaps even read build(7) I am sure that looking through the Makefile would be one of the last things on his mind. So, I am all in favor of documenting things but that should be done properly. What you did was not commenting the code (such comments usually appear near the code and describe the code), it was putting a mini-how-to at an obscure place. -- Andriy Gapon