NAV Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
:!: Python boilerplates have been implemented as described in the [[hacking#python_boilerplate_headers|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'':

<code python>
# -*- 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)"
</code>

From ''src/getDeviceData/src/getDeviceData.java'':

<code 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
 */
</code>

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

<code cheetah>
#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>
</code>

===== Discussion =====

The headers should have the following properties:

  * Need little, if any, maintenance over time.
  * Not repeat any information available elsewhere, like in VCS, except for legal reasons.
  * Waste as little monitor space as possible.

Comments on each of the typical header elements:

  * **Encoding:** This is actually used by Python for it to know how to work with non-ASCII symbols in the file. If it is not declared and the site's Python installation defaults to another encoding than what is used, Python will most probably crash. I.e. we should keep this, preferable using utf-8, add it where it is missing and convert iso-8859-1 files to utf-8. Most of our existing iso-8859-1 files does not contain any non-ASCII symbols except maybe in the author's names, and may thus be converted by just changing this header.
  * **Copyright:** NAV does mostly belong to two copyright holders, NTNU and UNINETT, and some contributed parts does have other copyright owners. In other words, this is a usefull field we should keep.
  * **License:** 15 lines of license information is not needed. I propose: "Released under the terms of the GNU General Public License version 2." Less is more.
  * **Authors:** Available in the VCS. Remove.
  * **SVN keywords:** $Id$ et al. are not useful anymore. Always remove these upon sight.
  * **Variables:** Readable to a human, just like the comments, but also easily extracted programatically. Only the ''%%__version__%%'' variable is mentioned in [[http://www.python.org/dev/peps/pep-0008/ | PEP 8]]. May be preferable to comments, but we do not extract them in any way, so lets just keep to the dead simple comments.

===== Proposed headers =====

==== Python ====

<code 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.
</code>

The first line may be dropped in non-executables. The second line is in conformance with [[http://www.python.org/dev/peps/pep-0263/ | 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 ====

<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.
</code>

==== Django templates ====

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

<code html>
{% 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 %}
</code>

==== Java ====

<code 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.
 */
</code>

===== Migration plan =====

How do we get rid of this mess?

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