[Tutor] Does the Python way of doing things have a definite preference for the structure and content of program file header comments?

[Alan Gauld]

On 23/01/15 07:02, Ben Finney wrote:

> An example::
>
>      # -*- coding: utf-8 -*-
>
>      # foo/frob.py
>      # Part of FooBar, a garden gnome decoration library.
>      #
>      # Copyright © 2011–2015 Ben Finney <ben+python at benfinney.id.au>
>      #
>      # This is free software: you may copy, modify, and/or distribute this work
>      # under the terms of the GNU General Public License as published by the
>      # Free Software Foundation; version 3 of that license or any later version.
>      # No warranty expressed or implied. See the file ‘LICENSE.GPL-3’ for details.

Note that much of the information in the true comment block should come 
from the VCS system. Most VCS systems provide a markup type mechanism 
that allows you to insert meta-data from the VCS into the file when 
checked out. Things like filename, version, author, and version number. 
Often the change comments too - but that can get very wordy.

For example in the (ancient) SCCS tool you could use:

# File: %M% %R%
#
# Date: %E%

And so on.

This helps prevent the VCS and the file from getting out of step but 
also provides the key meta data if a user does not have access to the 
VCS - eg picking up files from a memory stick on a laptop say.

-- 
Alan G
Author of the Learn to Program web site
http://www.alan-g.me.uk/
http://www.amazon.com/author/alan_gauld
Follow my photo-blog on Flickr at:
http://www.flickr.com/photos/alangauldphotos