Geomajas Community Documentation

2.1.1. Comment

Each file should have the correct copyright notice at the start of the file.
/*
 * This file is part of Geomajas, a component framework for building
 * rich Internet applications (RIA) with sophisticated capabilities for the
 * display, analysis and management of geographic information.
 * It is a building block that allows developers to add maps
 * and other geographic data capabilities to their web applications.
 *
 * Copyright 2008-2010 Geosparc, http://www.geosparc.com, Belgium
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program 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 Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

Note that the end year (shown here is 2010) should always be the current year. All headers will be updated at the beginning of each year.

  • The copyright message should be at the top of the file. However, for js files, it is allowed to have the "dojo.provide" line above the copyright as this helps for debugging.
  • Each class and interface should have class comments indicating the purpose of the class.
  • Public methods should be commented if the meaning is not entirely clear from method and parameter names (is it ever?). When the method overrides or implements a method, then repeating the javadoc is not needed.
  • Comments in the code are recommended when they explain a block of code or when they explain why things are done in a certain way. Repeating the code in human readable wording is wasteful.
  • Use "@todo" comments to indicate shortcuts or hacks which should be fixed. Better still is just to do it right and not have the shortcut.
  • All comments should be written in English.
  • Comments should be indented relative to their position in the code.
  • Javadoc comments should be active, not descriptive (for exampe on method "getXxx()" the comment could be "Get xxx").

  • All classes and interfaces need javadoc class comments.

  • All classes and interfaces in the geomajas-api module need full javadoc comments on all methods.

  • All classes, interfaces and methods which have a "@Api" annotation needs a "@since" javadoc comment to indicate the version in which the class or method was added. This is also the case for methods which are added in classes with "@Api(allMethods = true)" annotation.