Re: [Gzz-commits] gzz/doc/pegboard/coding_standard--vegai peg.rst

[Tuomas Lukka]

On Wed, Feb 05, 2003 at 03:04:51AM -0500, Vesa Kaihlavirta wrote:
>  
> -- import grouping is not resolved
> +- import grouping is not resolved?
> +
> +- Rule 1 needs rationale

It would be nice to always phrase the issues as complete, intelligible
questions, without too much reference below.

So these would be better as

- How should import statements be grouped?

- Does every file need to have its module name in the headers?

Then, when you mark these RESOLVED, explain the reason in detail.
That way, the issues section will be at its most useful, because
it then shows the points that were unclear at some point, as well
as their resolutions and the *reasons* for them.

>  Changes
>  =======
> @@ -49,8 +51,8 @@
>  
>  2. Header comments should include authors.
>  
> -3. After header comments, rcsid:
> -   rcsid = "$Id: peg.rst,v 1.13 2003/02/04 18:56:05 Vegai Exp $"
> +3. After header comments, rcsId:
> +   rcsId = "$Id: peg.rst,v 1.14 2003/02/05 08:04:49 Vegai Exp $"
>  
>  4. After rcsid, the imports (unless there's a good reason to delay
>     importing).
> @@ -87,16 +89,17 @@
>  
>  9. Functions and variables are mixedCase.
>  
> -10. Tab-size is 8 (will be converted to spaces by make committable), 
> indentation
> -    at 4 spaces.
> -
> -11. Never use tabs.
> +10. Tab-size is 8, indentation at 4 spaces.
>  
> +11. Run make committable before committing code.
>  
> +    - converts tabs to 8 spaces
> +    - runs tests

Uh, the rest is in passive tone and this would be better so as well.

>  Notes
>  =====
>  
> -- items 8-12 are arbitrary choices for the sake of consistency
> +- items 8 and 9 are arbitrary choices for the sake of consistency

This would be better as an issue.

- What case rules should be observed for variables and functions and modules?

        RESOLVED: modules should be lowercase and variables and functions 
mixedCase.
        This is the convention that is used in Java and we want to keep our Java
        and jython code as closely readable as possibly.

Again, stating the question that was posed at some point and the reasons
for resolving it a certain way.

This helps the reader. Even arbitrary choices have reasons in taste.

        Tuomas