[racket-dev] RFC: Coding Guidelines

Supplement it with those words but do leave the prose alone. This is a goal, just like smooth releases are. 

In general, I think we have reached a size and complexity and a turn-over (new people joining us and committing code) where we should have something to point them to. We're not asking you to rip out your code from the base. We're asking you to point your students to this set of strong suggestions. 

-- Matthias





On Aug 19, 2010, at 9:08 AM, John Clements wrote:

> 
> On Aug 17, 2010, at 4:27 PM, Jay McCarthy wrote:
> 
>> On Tue, Aug 17, 2010 at 2:24 PM, John Clements
>> <clements at brinckerhoff.org> wrote:
>>> 
>>> On Aug 17, 2010, at 3:57 PM, Jay McCarthy wrote:
>>> 
>>>> We're attempting to write down coding guidelines for the project.
>>>> 
>>>> Here is a first attempt:
>>>> 
>>>> http://faculty.cs.byu.edu/~jay/tmp/201008161509-guidelines.html
>>>> 
>>>> Please comment.
>>> 
>>> You write
>>> 
>>> "As long as your code fulfills its promises and meets each of these criteria, you can push incrementally.
>>> 
>>> For example, I may be working on adding an exhaustive queue library to Racket. I imagine supporting 30 different functions across 5 different queue implementations. I don't have to wait to push until all 150 function implementations are documented, tested, and stressed. I can push whenever I make progress on each of the required points."
>>> 
>>> Either this is contradictory, or I'm misunderstanding it.  The first paragraph suggests that the code must meet each of the criteria; the second suggests that as long as it's *closer* to meeting the required criteria, it's fine.
>> 
>> Maybe you can help me say it better. What I'm trying to get at is that
>> 150 functions is perfect to me, but if I only promise 30 functions and
>> meet the criteria for each of them, then I can commit even though it
>> is not "perfect". Progress here is meeting the 4 points for each new
>> function I push.
> 
> Okay, so every individual piece that's committed should meet the criteria.  I think that's the most sensible reading of what you wrote, but it also frightens me. I don't think that very much of our current code meets these criteria, and I'm worried that trying to enforce them is going to pull us into a sinkhole of no-new-functionality. I suppose that we should write down what we want before we figure out how to get there, though. 
> 
> As far as this piece text is concerned, I think I would replace that last sentence with essentially what you wrote in response:
> 
>>> For example, I may be working on adding an exhaustive queue library to Racket. I imagine supporting 30 different functions across 5 different queue implementations, for a total of 150 functions.  If I have just 30 of these documented, tested, and stressed, then it's fine for me to push.
> 
> 
> John
> 
> _________________________________________________
>  For list-related administrative tasks:
>  http://lists.racket-lang.org/listinfo/dev