Table of Contents

:!: Python boilerplates have been implemented as described in the HACKING document. Boilerplates for other languages have not been provided, but should be similar in style to the Python ones.

:!: This page is now only here for historic purposes.

Source file headers

Most of the source files in NAV got large header sections. What the headers contain varies a bit, but it is generally some information about file encoding, copyright holder, license, authors, and often copyright, license and authors again, as “meta-variables” instead of comments. This information is regularly outdated and results in the fun (i.e. the code) does not start before line 30, or line 50 if we declare imports boring. Most of our headers are also polluted by $Id$ and similar SVN keywords, which has no meaning now when we are using Mercurial.

Is this really necessary? What is optimal?

Current examples

From subsystem/ipdevinfo/nav/web/ipdevinfo/views.py:

# -*- coding: utf-8 -*-
#
# Copyright 2007-2008 UNINETT AS
#
# This file is part of Network Administration Visualized (NAV)
#
# NAV is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# NAV is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with NAV; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
#
# Authors: Stein Magnus Jodal <stein.magnus.jodal@uninett.no>
#
 
__copyright__ = "Copyright 2007-2008 UNINETT AS"
__license__ = "GPL"
__author__ = "Stein Magnus Jodal (stein.magnus.jodal@uninett.no)"

From src/getDeviceData/src/getDeviceData.java:

/*
 * getDeviceData
 * 
 * $LastChangedRevision: 3500 $
 *
 * $LastChangedDate: 2006-07-05 14:23:14 +0200 (ons, 05 jul 2006) $
 *
 * Copyright 2002-2004 Norwegian University of Science and Technology
 * 
 * This file is part of Network Administration Visualized (NAV)
 * 
 * NAV is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * NAV is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with NAV; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

From subsystem/webfront/nav/web/templates/MainTemplate.tmpl:

#encoding UTF-8
## $Id$
##
## Copyright 2003-2005 Norwegian University of Science and Technology
## Copyright 2006 UNINETT AS
##
## This file is part of Network Administration Visualized (NAV)
##
## NAV is free software; you can redistribute it and/or modify
## it under the terms of the GNU General Public License as published by
## the Free Software Foundation; either version 2 of the License, or
## (at your option) any later version.
##
## NAV is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
## GNU General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with NAV; if not, write to the Free Software
## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
##
##
## Authors: Magnar Sveen <magnars@idi.ntnu.no>
##          Stein Magnus Jodal <stein.magnus.jodal@uninett.no>

Discussion

The headers should have the following properties:

Comments on each of the typical header elements:

Proposed headers

Python

#! /usr/bin/env python
# -*- coding: utf-8 -*-
 
"""A line describing this module."""
 
# Copyright (C) 2002-2004 Norwegian University of Science and Technology
# Copyright (C) 2007-2008 UNINETT AS
# Released under the terms of the GNU General Public License version 2.

The first line may be dropped in non-executables. The second line is in conformance with PEP 0263 and should also be recognized by i.e. Emacs and VIM. The docstring marks the start of the code, now at line 4 instead of 20. I.e. the copyright which must be kept up to date is now mentally a part of the code.

Cheetah

#encoding UTF-8
##
## A line describing this template.
##
## Copyright (C) 2002-2004 Norwegian University of Science and Technology
## Copyright (C) 2007-2008 UNINETT AS
## Released under the terms of the GNU General Public License version 2.

Django templates

We do not currently have any headers in the Django templates.

{% comment %}
A line describing this template.
 
Copyright (C) 2002-2004 Norwegian University of Science and Technology
Copyright (C) 2007-2008 UNINETT AS
Released under the terms of the GNU General Public License version 2.
{% endcomment %}

Java

/*
 * A line describing this module.
 *
 * Copyright (C) 2002-2004 Norwegian University of Science and Technology
 * Copyright (C) 2007-2008 UNINETT AS
 * Released under the terms of the GNU General Public License version 2.
 */

Migration plan

How do we get rid of this mess?

  1. Cleanup the header of all files you edit. Remember the Boy Scout Rule: Leave the camp ground cleaner than you found it.
  2. If you have nothing else to do: Cleanup larger groups of files, i.e. entire subsystems.