svn commit: r253002 - head

[Andriy Gapon]

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