Author: allison Date: Tue Dec 30 18:53:27 2008 New Revision: 34684 Modified: trunk/docs/pdds/pdd07_codingstd.pod
Log: [pdd] Remove the 'HISTORY' section from expected documentation, as it is no longer used. Be explicit on our policy about author information in individual files. Remove a legacy perl6-ism. Modified: trunk/docs/pdds/pdd07_codingstd.pod ============================================================================== --- trunk/docs/pdds/pdd07_codingstd.pod (original) +++ trunk/docs/pdds/pdd07_codingstd.pod Tue Dec 30 18:53:27 2008 @@ -840,11 +840,6 @@ successors, e.g. benchmarks of differing hash algorithms, essays on how to do integer arithmetic. -=item HISTORY - -Record major changes to the file, e.g. "we moved from a linked list to a hash -table implementation for storing Foos, as it was found to be much faster". - =item SEE ALSO Links to pages and books that may contain useful information relevant to the @@ -852,6 +847,10 @@ =back +Don't include author information in individual files. Author information can be +added to the CREDITS file. (Languages are an exception to this rule, and may +follow whatever convention they choose.) + =item Per-section comments If there is a collection of functions, structures or whatever which are @@ -924,15 +923,13 @@ =head2 Extensibility -If Perl 5 is anything to go by, the lifetime of Perl 6 will be at least -seven years. During this period, the source code will undergo many major -changes never envisaged by its original authors -- c.f. threads, unicode in -perl 5. To this end, your code should balance out the assumptions that make -things possible, fast or small, with the assumptions that make it difficult -to change things in future. This is especially important for parts of the -code which are exposed through APIs -- the requirements of source or binary -compatibility for such things as extensions can make it very hard to change -things later on. +Over the lifetime of Parrot, the source code will undergo many major changes +never envisaged by its original authors. To this end, your code should balance +out the assumptions that make things possible, fast or small, with the +assumptions that make it difficult to change things in future. This is +especially important for parts of the code which are exposed through APIs -- +the requirements of source or binary compatibility for such things as +extensions can make it very hard to change things later on. For example, if you define suitable macros to set/test flags in a struct, then you can later add a second word of flags to the struct without breaking source
