Etiquetas: coding conventions

This document is part of the Liferay Core Development Guidelines.

Introduction #

There is one rule when working with Liferay's source code that you should always keep in mind:

Follow the patterns and conventions of the existing code

This means that even if you think you can do it better, don't. If you really want to do it in a different way you should first discuss it with the other developers. If it's accepted as a better way of doing something, it should be applied throughout all the source code to ensure that consistency is maintained.

Java Code Style #

When not explicitly define otherwise follow the Code Conventions for Java

Names #

  • Private methods, fields and constants start with underscore
  • Private constants and fields should be at the end of the file

Line breaks #

All code must have less than 80 columns to make it easier to print. The following rules describe how long lines should be broken:

  • Break long method param lists right after the opening parenthesis like in:
String messageId = MBUtil.getMailId(
	message.getMessageId(), company.getCompanyId());

instead of:

String messageId = MBUtil.getMailId(message.getMessageId(),
	company.getCompanyId());

But if the line still longer, then break after the equals sign:

String messageId =
	MBUtil.getMailId(message.getMessageId(), company.getCompanyId());
  • The next line on a long line break should have a one tab padding
  • Indent method parameters as in the following example:
myMethod(
	oneParamter, anotherParameter,
	andOneMore, andTheLastOne);
  • Leave one blank line before the last curly bracket which closes the class

Vertical and horizontal spaces #

  • Use tabs where possible (configure editor to use the equiv. of 4 spaces)
  • Use empty lines to separate the code and make it easier to use
    • One line between related code blocks
    • One line to separate methods
    • One line just before the end } of a class definition
  • Do not use more than one line as a separator

Ordering #

  • Always order lists of items alphabetically. For example:
    • Group related imports and order each group alphabetically
    • Group public methods first, private last and order each group alphabetically (see listing below) with the only exception of getters and setters which should be together
    • When the names of the methods are the same order by the arguments
    • In Model classes and interfaces order getters+setters by importance of the field (this is an exception to the alphabetical order used elsewhere)
    • In Service classes order the methods alphabetically
    • Idem with fields
    • Order Exceptions in throws clauses alphabetically
  • Do not use 'this' to refer to fields (they are already different because of the underscore prefix)
  • Exhaustive List of Ordering
public static CONSTANTS
public static variables
public static methods


public constructors
public methods
public variables


public static classes
public classes


protected static methods
protected constructors
protected methods


protected static CONSTANTS
protected static variables
protected variables


protected static classes
protected classes


private static methods
private constructors
private methods


private static _CONSTANTS
*private static _variables
private _variables


private static classes
private classes

*for private static variables, the following variables always come first (if applicable)


_log
_instance
  • Tie breakers
    • (from first to last): static final, static, final
    • (from first to last): alphabetical.. a --> z
  • ie: if a class contained a public, static, final, variable starting with the letter A, it would always be at the very top of the file
  • ie: if a class contained a private, non-static, non-final, method with the letter Z, it would always be at the very bottom of the file

Methods in {Model}ServiceImpl classes #

  • They should be ordered alphabetically
  • They should only return either instances of Model or lists of instances of Model
    • Example: TagsEntryLocalService can only return TagsEntry or Lists of TagsEntry
    • Reason: Because the soap generator then knows how to convert List to a typed array

Processing order within add and delete methods in {Model}ServiceImpl classes #

When "adding":

  1. expando
  2. model
  3. resource
  4. portal package
  5. local package
  6. other package
  7. indexer
  8. status
  9. file
  10. email / subscribers
  11. ping

When "deleting":

  1. model
  2. resource
  3. portal package
  4. local package
  5. other package (expando is in here)
  6. indexer
  7. status
  8. file
  9. email / subscribers
  10. ping

Logging #

  • Use Kernel Logging (com.liferay.portal.kernel.log.)
  • Create a private static final _log variable and declare it at the bottom of the file
  • Use the Liferay Logging page to decide which log level to use

Comments #

  • Always have exactly 1 blank line before and after comments.
PasswordPolicy passwordPolicy = user.getPasswordPolicy();

// Check if password has expired

if (isPasswordExpired(user)) {

}
  • On the occasion that you need multiple sentences for your comments, only have one space after the period.

Other #

  • Use the keyword 'public' for all methods of an interface (it's not required by Java but we like to make it explicit)
  • import clauses should always point to specific classes and not use the 'package.' syntax
  • Do never leave unused import clauses
  • Copyright and class Javadoc: Every file should have them. Copy them from any file of the same type (java, JSP, JSPF, ...)
  • Class javadoc should have a link to the HTML version of the class (which will be generated by ant) and at least one @author tag
  • Add an empty line after the @author tag

JSP coding rules #

  • Use the jsp extension for JSPs invoked from struts or tiles or included dynamically
  • Use the jspf extension for JSPs included statically

JavaScript (and jQuery) Code Style #

Quotes #

Our convention is just always use single quotes for strings everywhere in Javascript. The reason we do it this way is because this: jQuery('<a class="modify-link" href="javascript: ;"></a>')

looks more readable than this: jQuery("<a class=\"modify-link\" href=\"javascript: ;\"></a>")

(especially on large html blocks).

Events #

When triggering an event (like change) which is not naturally fired we prefer to use: trigger('event name') instead of methods like change(), dblclick()... etc The reason is that these events are not naturally fired for anything except for form elements, but jQuery allows us to trigger custom events that aren't natively supported. Especially in cases like this, we prefer to use trigger('event name') so that it's explicit that we're triggering an event.

Tools #

Source Formatter #

See main article: Source Formatter

IDE Source Formatting Tools #

Many integrated development environments provide the ability to format your source code, and you can use them to apply several of the Java Coding Style conventions to your existing source code.

IntelliJ: Arranging code with IntelliJ

Eclipse: Eclipse and Liferay coding conventions

Subpáginas

2 archivos adjuntos
62363 Accesos
Promedio (5 Votos)
La valoración media es de 4.0 estrellas de 5.
Comentarios
Respuestas anidadas Autor Fecha
With regard to the "Exhaustive List of... Bijan Vakili 28 de mayo de 2010 16:00
Sorry for the double-post, I meant the... Bijan Vakili 28 de mayo de 2010 16:03
Please check the updated order you are taking... Igor Spasić 21 de junio de 2010 2:08
Unfortunatelly the sample Eclipse configuration... Vilmos Papp 2 de noviembre de 2010 8:56
Thanks a lot :-) sandhya shendre 21 de enero de 2011 2:16
Eclipse configuration now attached. Richard Sezov 27 de mayo de 2011 7:33

With regard to the "Exhaustive List of Ordering"

Shouldn't the actual ordering be:
* Public
o variable
o constructor
o method
* Protected
o constructor
o method
o variable
* Private
o constructor
o method
o variable

The ordering in this wiki seems ok, but in the code it is as I mentioned above. For reference, please see the following variables:
*com.liferay.portal.service.persistence.OrganizationFinderImpl.COUNTRY­_ID_SQL
*com.liferay.portal.dao.db.BaseDB.ALTER_COLUMN_TYPE

Thanks.
Publicado el día 28/05/10 16:00.
Sorry for the double-post, I meant the following ordering instead:
* Public
o variable
o constructor
o method
* Protected
o constructor
o method
* Private
o constructor
o method
* Protected
o variable
* Private
o variable

Thanks.
Publicado el día 28/05/10 16:03 en respuesta a Bijan Vakili.
Please check the updated order you are taking about emoticon
Publicado el día 21/06/10 2:08 en respuesta a Bijan Vakili.
Unfortunatelly the sample Eclipse configuration file is not found on the url :-(
Publicado el día 2/11/10 8:56.
Publicado el día 21/01/11 2:16.
Eclipse configuration now attached.
Publicado el día 27/05/11 7:33 en respuesta a sandhya shendre.